API Specifications

Provides OpenAPI Specification (v3) definitions for Nexmo APIs.

Human-readable specifications

View rendered API specifications

(Raw specification files are in definitions/)

About OpenAPI

These definitions provide a single point of truth that can be used end-to-end:

Planning Shared during product discussions for planning API functionality
Implementation Inform engineering during development
Testing As the basis for testing or mocking API endpoints
Documentation For producing thorough and interactive documentation
Tooling To generate server stubs and client SDKs.

Resources

Tools

Stoplight Studio - powerful spec editor with validation and local mock server
Nexmo OAS Renderer - Nexmo's tool for rendering OpenAPI specs to HTML.
Nexmo Developer - Nexmo Developer uses these specs and the renderer for the API reference pages.

Check your API spec for validity and style

We use Spectral to style and validity check our files. If you're using Stoplight Studio, this picks up our style definition by default. Otherwise, you can install the tool locally like this:

npm install -g @stoplight/spectral

And check your file (for example verify.yml):

spectral lint definitions/verify.yml

This runs the same checks that we use in the build that runs when you open a pull request.

In addition to semantic linting, we use Prettier to enforce consistent formatting.

To run prettier locally:

npm install -g prettier
prettier --list-different definitions/**/*.yml

You can auto-format your specifications with the following command, but we recommend installing a Prettier plugin in your IDE to format on save:

prettier --write definitions/**/*.yml

Contributing

Contributions are welcome, please follow GitHub Flow