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

The Potential of the OpenAPI Spec Parameters Object

DZone's Guide to

The Potential of the OpenAPI Spec Parameters Object

Providing detail on each parameter can make an API definition more accessible. Learn more in this article from Kin Lane.

· Integration Zone
Free Resource

The Integration Zone is brought to you in partnership with Cloud Elements. What's below the surface of an API integration? Download The Definitive Guide to API Integrations to start building an API strategy.

I enjoy learning from the OpenAPI Specs of the API providers who I track. Just having an OpenAPI Spec present tells a lot about an API provider in my book, but the level of detail some providers put into their API definitions adds another level to this for me. While reviewing the OpenAPI Spec for the Oxford Dictionaries API, I noticed their robust usage of the OpenAPI Spec parameters definitions collection. It provides an interesting overview of the surface area of the API, augmenting the benefits brought to the table by the definitions collection of an APIs underlying data schema.

When you are defining each path for an API you can either define the parameters using each paths parameters, or you can add them to the overall parameters definition object, allowing them to be reused across all paths. This object provided me with a centralized place to learn about the parameters used when making calls to the Oxford Dictionary API, and I'm assuming it helped them be more organized in how they defined the surface area of their APIs.

I can see how the processing of defining each path's parameters and centrally organizing them for reuse can be a healthy thing. The more you lift yourself out of the individual definition of each path and consider the parameter patterns that have been used for other paths, the chances you will have a better view of the landscape will increase. I am optimistic about this OpenAPI Spec object and curious about how it can be evolved as part of other conversation around GraphQL (something I'll work to understand better in the future).

Your API is not enough. Learn why (and how) leading SaaS providers are turning their products into platforms with API integration in the ebook, Build Platforms, Not Products from Cloud Elements.

Topics:
integration ,open api ,open api spec

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}