A presentation at PHP[TEK] in in Atlanta, GA, USA by Lorna Jane Mitchell
Leveraging API Specification Languages Lorna Mitchell, Nexmo
Describing APIs • Describe RESTful HTTP APIs in a machine-readable way Then the machine can read it and write: • API reference documentation • Code SDKs • Postman collections • Mock servers @lornajane
API Spec Languages • OpenAPI is an open standard, and is used in this talk • RAML from Mulesoft (who also now support OpenAPI) • API Blueprint from Apiary @lornajane
Spec-First API Design @lornajane
New APIs or Existing Ones? @lornajane
New APIs or Existing Ones? Yes! @lornajane
Anatomy of OpenAPI Spec @lornajane
Anatomy of OpenAPI Spec Top-level elements: • openapi • info • servers • paths • components • security • tags @lornajane
OpenAPI Spec Examples 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.3 description: >Nexmo’s Number Insight API delivers real-time intelligence about the validity … a few hundred more lines here @lornajane
Documenting an Endpoint paths: ‘/basic/{format}’: parameters: - $ref: ‘#/components/parameters/format’ get: operationId: getNumberInsightBasic parameters: - $ref: ‘#/components/parameters/number’ - $ref: ‘#/components/parameters/country’ responses: ‘200’: description: OK content: application/json: schema: $ref: ‘#/components/schemas/niResponseJsonBasic’ @lornajane
Reference Parameters components: parameters: number: name: number in: query description: ‘A single phone number that you need insight about in national example: ‘447700900000’ required: true country: name: country in: query example: ‘GB’ description: ‘If a number does not have a country code or is uncertain, set schema: type: string pattern: ‘[A-Z]{2}’ @lornajane
That looks complicated! @lornajane
Editing Tools There are editors with helpful tools • Stoplight is highly recommended if you like a web interface https://stoplight.io • I like Atom with linter-swagger https://atom.io • Try SwaggerUI, SwaggerHub, etc https://swagger.io/tools/ • APICurio Studio gets good reviews https://www.apicur.io/ @lornajane
Please use Source Control See also: https://gitworkbook.com @lornajane
Validation Tools Tools that check or “lint” your file. • Speccy is a CLI tool with configurable rules http://speccy.io/ • Spectral is a newer CLI tool, also with rules https://github.com/stoplightio/spectral • Open API Spec Validator https://github.com/p1c2u/openapi-spec-validator @lornajane
Preview Tools OAS is a standard! So any preview should do: • ReDoc is great https://github.com/Rebilly/ReDoc • You can run OpenApi-GUI locally https://github.com/mermade/openapi-gui • Nexmo uses a custom renderer https://developer.nexmo.com/api • Stoplight shows documentation as you go (more on this later) https://stoplight.io @lornajane
Docs Example: ReDoc @lornajane
Docs Example: Nexmo @lornajane
Docs Example: Stoplight @lornajane
Stoplight Online Editor @lornajane
Stoplight Design View @lornajane
Imported into Postman @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
Creating OpenAPI Specs is like eating an elephant @lornajane
Uses for OpenAPI Spec @lornajane
Resources • https://www.openapis.org • https://openapi.tools • https://apievangelist.com • https://stoplight.io • https://speccy.io • https://github.com/Rebilly/ReDoc • https://github.com/openapitools/openapi-generator @lornajane
Open API Specification is a machine and human readable way to describe APIs. From these specs we can generate documentation, create libraries, and ensure that our users know exactly what to expect from our APIs. This talk shows you around OAS from the beginning, showing how to create the specs and recommending some tools to help the process. Once you have the spec, things get interesting and this talk will showcase some of the things that you can offer once your API is described in this way. This session is recommended for writers looking to become more API-savvy and API engineers wanting to make their APIs more useful to their users.
