Power Your API Workflow With OpenAPI

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