Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Nexmo Manages Their OpenAPI 3.0 Definition Using GitHub

DZone's Guide to

Nexmo Manages Their OpenAPI 3.0 Definition Using GitHub

In this article, we take a look at what one organization is doing to push forward the concept of open APIs and open source code.

· Integration Zone ·
Free Resource

SnapLogic is the leading self-service enterprise-grade integration platform. Download the 2018 GartnerMagic Quadrant for Enterprise iPaaS or play around on the platform, risk free, for 30 days.

I’m big on supporting API providers that publish their OpenAPI definitions to GitHub. It is important for the wider API community that ALL API definitions are machine-readable and available in a way that can be forked and integrated into continuous integration pipelines. I’m not even talking about the benefits to the API providers when it comes to managing their own API lifecycle. I’m just focusing on the benefits to API consumers, and helping to make onboarding, integration, and keeping in sync with the roadmap as frictionless as possible.

To help incentivize API providers doing this, I’m committed to writing up stories for each API provider that publishes their OpenAPI, APIs.json, or Postman Collections to GitHub. Bonus points if you are doing it in an interesting way that further benefits your operations, as well as your community. Today’s API provider to showcase is the SMS, voice and phone verifications API provider Nexmo, who tweeted the GitHub repository at me, which contains their OpenAPI definition for their APIs. As they say, it is a work in progress, but it provides a damn good start for a machine-readable definition for their API(s), and I mean c’mon, aren’t all of our APIs a work in progress?

Nexmo uses their API definition as, “a single point of truth that can be used end-to-end for:”

  • Shared planning during product discussions for planning API functionality.
  • Implementation to 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.

Nexmo has adopted version 3.0 of the OpenAPI definition, which is forward leaning for the API provider. They also provide a list of resources, tooling, and their API definition available as Ruby packages for easier integration. Another thing they do that I think is interesting, is they list the owner, and contributors for each API definition they have published, or are working on. Which is a concept I fully support and would like to bake into my own API stack work. Working on API definitions is hard work, and we should be showcasing, and supporting anyone that steps up to do the hard work, as well as providing a point of contact for each available definition.

I am going to spend some time going through Nexmo’s API definition and learning more about OpenAPI 3.0. I will also be spending time going through their API developer portal creating an APIs.json and Postman Collection for their API. I’m looking to add their API to the Postman API Network, as well as my API Stack, Streamdata.io API Gallery, and other API aggregation, integration, and discovery projects I am working on. Thanks for bringing this to my attention Nexmo, and keep up the good work! I’ll keep paying attention to what you are doing, with GitHub and your OpenAPI definition being a conduit for guiding my attention.

With SnapLogic’s integration platform you can save millions of dollars, increase integrator productivity by 5X, and reduce integration time to value by 90%. Sign up for our risk-free 30-day trial!

Topics:
integration ,openapi ,github ,api development ,open source

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}