Introduction to OpenAPI

Introduction to OpenAPI Lorna Mitchell, Nexmo

APIs are the engine of modern software development API descriptions power up our API workflows @lornajane

Spec-First API Design @lornajane

New APIs or Existing Ones? @lornajane

New APIs or Existing Ones? Yes! @lornajane

API Description Languages • API Blueprint from Apiary • RAML from Mulesoft (who also now support OpenAPI) • OpenAPI is an open standard, and is used in this talk • “The standard formerly known as Swagger” @lornajane

OpenAPI Descriptions WARNING may contain YAML @lornajane

MetaData openapi: 3.0.0 servers: - url: ‘https://api.nexmo.com/ni’ info: title: Number Insight API version: 1.0.4 description: Nexmo’s Number Insight API delivers real-time intelligence … contact: name: Nexmo DevRel email: devrel@nexmo.com url: ‘https://developer.nexmo.com/’ termsOfService: ‘https://www.nexmo.com/terms-of-use’ license: name: ‘The MIT License (MIT)’ url: ‘https://opensource.org/licenses/MIT’ @lornajane

Endpoints in OpenAPI Spec paths: ‘/basic/{format}’: get: operationId: getNumberInsightBasic ‘/standard/{format}’: get: operationId: getNumberInsightStandard ‘/advanced/async/{format}’: get: operationId: getNumberInsightAsync ‘/advanced/{format}’: get: operationId: getNumberInsightAdvanced @lornajane

Parameters and Responses parameters: - $ref: ‘#/components/parameters/format’ - $ref: ‘#/components/parameters/number’ - $ref: ‘#/components/parameters/country’ responses: ‘200’: description: OK content: application/json: schema: $ref: ‘#/components/schemas/niResponseJsonBasic’ text/xml: schema: $ref: ‘#/components/schemas/niResponseXmlBasic’ @lornajane

OpenAPI $ref Feature (Re)Use any block. For example the format parameter: components: parameters: format: name: format in: path required: true description: ‘The format of the response’ example: json schema: type: string enum: - ‘json’ - ‘xml’ @lornajane

That’s a lot of YAML … @lornajane

How to Edit OpenAPI Specs Option 1: your usual editor (this is https://atom.io) @lornajane

Text-Based API Descriptions @lornajane

How to Edit OpenAPI Specs Option 2: specialist tool https://stoplight.io/studio/ @lornajane

Validate and Check Style Spectral https://github.com/stoplightio/spectral Pick-and-mix the rules, and sprinkle in a few of your own! @lornajane

Even the machines can understand … now what? @lornajane

Generate Documentation Use your OpenAPI spec as the source for your API reference documentation • A choice of tools • Separate content and presentation • The spec supports and encourages examples @lornajane

Docs Example: ReDoc @lornajane

Docs Example: Nexmo @lornajane

Explore APIs with Postman @lornajane

OpenAPI Spec To Mock Server Prism is a mock server https://stoplight.io/prism/ @lornajane

Generated Code Libraries This example is from OpenAPI Generator https://github.com/OpenAPITools/openapi-generator docker run —rm -v ${PWD}:/local \ openapitools/openapi-generator-cli generate -i number-insight.yml -g php -o /local/out/php @lornajane

Generated Code Libraries To use it: 1 2 3 4 5 6 7 8 9 10 11 12 13 require_once(‘out/php/vendor/autoload.php’); // copy code from README, set API key and secret $apiInstance = new OpenAPI\Client\Api\DefaultApi( new GuzzleHttp\Client(), $config); $format = “json”; $number = “447700900000”; try { $result = $apiInstance->getNumberInsightBasic($format, $number); print_r($result); } catch (Exception $e) { echo ‘Exception when calling DefaultApi->getNumberInsightBasic’; } @lornajane

Finding Tools https://openapi.tools - a community listing @lornajane

OpenAPI: Brave New World @lornajane

Resources • https://developer.nexmo.com • https://openapis.org • https://stoplight.io (Studio, Prism and Spectral) • https://github.com/Nexmo/nexmo-oas-renderer • https://github.com/Redocly/redoc • https://openapi.tools @lornajane

@lornajane

Introduction to OpenAPI Lorna Mitchell, Nexmo