A presentation at Vonage Campus in in San Francisco, CA, USA by Lorna Jane Mitchell
Power Your API Workflow With OpenAPI Lorna Mitchell Nexmo, the Vonage API Platform
What is OpenAPI? An API description standard, in YAML/JSON • https://openapis.org • Text-based works well with source control • Formerly known as “Swagger” @lornajane
We LOVE OpenAPI!
Explore New APIs Get started more quickly by using OpenAPI with your existing tools: • Import your OpenAPI spec into Postman https://getpostman.com • Also try this trick with: Paw, Insomnia, maybe your IDE? @lornajane
Great Resources OpenAPI is a great basis for excellent documentation. @lornajane
Open Standard: Open Tools https://developer.nexmo.com uses nexmo_oas_renderer gem install nexmo-oas-renderer export OAS_PATH=specs nexmo-oas-renderer The spec(s) can be found at https://localhost:4567 GitHub: https://github.com/Nexmo/nexmo-oas-renderer Or try ReDoc https://github.com/Redocly/redoc npm install -g redoc-cli redoc-cli serve specs/openapi.yml @lornajane
Single Source, Many Outputs Content and presentation are separate, here’s ReDoc rendering: @lornajane
Easy Integrations • First Choice: API provider’s SDKs • Nexmo publishes SDKs for 7 tech stacks • Backup Plan: Generate a local code wrapper to access an API @lornajane
Generated Code Libraries This example uses 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
Inside an OpenAPI Spec Warning: may contain YAML
Anatomy of OpenAPI Spec Top-level elements: • openapi • info • servers • paths • components • security • tags @lornajane
OpenAPI Spec Example A JSON or YAML file holds the description (this is YAML) 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 license: url: ‘https://opensource.org/licenses/MIT’ … a few hundred more lines here @lornajane
OpenAPI Spec Example Here’s an endpoint, in paths paths: ‘/basic/{format}’: parameters: - $ref: ‘#/components/parameters/format’ get: operationId: getNumberInsightBasic summary: Basic Number Insight description: | Provides [basic number insight](/number-insight/overview#basic-standard-a information about a number. parameters: - $ref: ‘#/components/parameters/number’ - $ref: ‘#/components/parameters/country’ @lornajane
OpenAPI Spec Example We can $ref to elements that are reused, like this format parameter that is in the path of every request for this API: format: name: format in: path required: true description: ‘The format of the response’ example: json schema: type: string enum: - ‘json’ - ‘xml’ @lornajane
OpenAPI Spec Example Responses are organised by status code: responses: ‘200’: description: OK content: application/json: schema: $ref: ‘#/components/schemas/niResponseJsonBasic’ text/xml: schema: $ref: ‘#/components/schemas/niResponseXmlBasic’ @lornajane
Text-based Specifications • Work brilliantly with source control • We keep our API specs publicly: in GitHub https://github.com/nexmo/api-specification • Brought into https://developer.nexmo.com as a dependency • Enables our other workflows - and yours! @lornajane
changelog.nexmo.com @lornajane
OpenAPI Brings Power to Your API Workflow
Resources • Get in touch! @lornajane or @NexmoDev on Twitter • https://developer.nexmo.com • https://changelog.nexmo.com • https://github.com/nexmo • https://openapis.org @lornajane
Have you noticed how many of your favourite API providers are offering their specs in OpenAPI format now? This session will introduce you to OpenAPI and why API providers are increasingly offering it to their users to enable adoption and make integrations easier. Learn about the format, the tools, and how an OpenAPI description can help you to get on board with a new API - or of course help your customers adopt your own APIs. We’ll be sharing why we chose OpenAPI, our workflows, and the tools we use.
