Standards are awesome. What kind of world would this be if programming languages allowed and and to be used interchangeably or even mixed together? Chaos would ensue. () [] {} What if the port on the side of your computer was simply a jumble of loose wires and contacts, waiting for you to find the right combination of connections to power up your webcam? Thank goodness for the USB standard. Building your application on top of unpredictable and unreliable APIs is a time-killer. It’s just one headache after another. That’s why the industry standard used by both builders consumers of APIs. APIs need standards, too. API development has moved toward broad adoption of the OpenAPI Specification (OAS)— and How might OAS help as you build systems that consume APIs? What are the pitfalls you’ll avoid by using APIs that adhere to OAS? Ultimately, an API is most usable when it conforms to a standard. In addition to OAS-conformant APIs being more usable, OAS has led to several tools—like and —built for developers to better understand the APIs they’re working with. Swagger comprises a suite of tools used for the design, development, documentation, and testing of APIs. APIClarity observes real-time traffic to and from an API, and then compares usage against the API’s specification. Swagger APIClarity actual Let’s look at how the OpenAPI Specification came about and then dive into how adopting OAS will remove the headaches and bring confidence back to your integration of third-party APIs. What is the OpenAPI Initiative? The OpenAPI Initiative (OAI) is “ .” The OAI include big hitters like IBM, Google, Oracle, MuleSoft, and Kong. a consortium of forward-looking industry experts who recognize the immense value of standardizing how APIs are described consortium members When establishing the standard, the goal of the OAI is to bring value to developers on both sides of an API. , the standard provides a framework for building reliable services that interact with others. That framework nudges you toward best practices for security and future-proofing your development. The APIs you build can become predictable and reliable. By using a standard format to document your API, your API becomes more discoverable. For developers constructing the API , the benefits are even greater: interacting with an API that conforms with a standard provides assurance that the API you use will be and . You also reap the benefit of API , as APIs documented according to OAS will be more easily findable in API marketplaces or exchanges. For developers consuming APIs predictable reliable discoverability OAI operates under the Linux Foundation as a partnership between many industry-leading companies. Developers and consumers of APIs that adhere to OAS can take comfort in knowing that those APIs are vendor-neutral and rely on well-known web technologies. OAS itself was initially based on the and continues to have many elements drawn from Swagger’s popular API documentation tool. Additionally, OAS targets RESTful API development and the resource-driven API model. Swagger Specification Why Use OAS? When an API is designed, built, and consumed in adherence to a standard, it benefits both the maintainers and the users of the API. There’s no more lost time or guesswork trying to figure out whether the params were supposed to be in the query string or in the request body, or whether authentication in the header was basic auth or bearer auth. Developer confidence and velocity—for builders and consumers increases, since conventions lead to code consistency. With the OpenAPI Specification, developers enjoy many benefits and avoid common pitfalls. Benefits enjoyed One of the biggest benefits of the OAS is the definition of a convention—a standard, . OAS-conformant APIs can be implemented in any language and with any number of services underlying them. The specification is of the API which it describes. The specification simply details the function of the API. language-agnostic interface completely decoupled from the implementation details This separation from the implementation is a benefit to both developers and consumers of an API service, as it . With a specification in hand, an API consumer can without needing to know the language or framework in which the API was developed. Consumers will not need access to any source code or specialized documentation. For example, consumers of the would have all they need for API usage from an OAS document, without needing to learn Ruby on Rails or Go, which are part of the Twitch tech stack. Similarly, users of the don’t need to learn Python or Java to use the API. This is the benefit of OAS being language-agnostic. eases the discoverability of different functions of the system easily understand the API Twitch API Spotify API Because the OpenAPI Specification is so widely used and agreed upon across the industry, numerous . There are tools to validate requests (such as or ), automate the writing of API documentation (such as or ), and even generate SDK code for many client languages (such as or ). While an API developer can certainly go it alone and build without any assistance, it’s certainly helpful to have many toolchain options when building an OAS-conformant API. tools have been built to simplify the task of API development Dredd RESTest Stoplight DeveloperHub APIMatic CodeGen OpenAPI Generator Pitfalls avoided Additionally, using an OAS-conformant API ensures you don’t fall victim to many common pitfalls. because the standard ensures the usage of HTTP methods. Endpoints across an API are guaranteed to be consistent You also won’t need to worry about running into deprecated APIs (sometimes called “zombie APIs”), as the . OAS-conformant APIs won’t introduce breaking changes within the same version; instead, breaking changes would require a version change in the API. standard ensures reasonable versioning of the API Undocumented APIs (or “shadow APIs”) are also avoided when using OAS-conformant APIs, because the standard requires developers to in their APIs. use an understandable and agreed-upon structure Enforcing OAS Adherence With all that the OpenAPI Specification promises, it may seem daunting to ensure that the APIs you consume are OAS-conformant. The task of building an API that adheres to OAS may seem equally formidable. It doesn’t need to be. To begin with, the tools around the OpenAPI Specification are a huge asset for any developer working in the space. Since OAS was originally based on the Swagger Specification, there are still from Swagger that can help any developer working on an API. many tools For API developers, the OpenAPI Initiative provides a useful for building robust OAS-conformant APIs. Whether you need code generation or documentation assistance, there’s probably something for you there. list of tools When building API-consuming client applications, helpful tools include those used for . Some of these tools can run against that API you want to use, generating a description of the API according to the OAS standard. learning more about the APIs you consume For example, is a tool that observes all of the API traffic within your Kubernetes environment. Based on traffic observation, APIClarity infers an OpenAPI description for those APIs. APIClarity This is especially helpful if the API creator never defined or provided such a description. It also surfaces potential problems with existing APIs, such as requests made to undocumented, shadow APIs or continued use of deprecated, zombie APIs. If you’re getting started on the path toward OAS compliance, then tools like APIClarity can be a great source of insight and observability. Conclusion In summary, the OpenAPI Specification exists to make a developer’s work much easier—whether they build or consume APIs. Rather than making design decisions on the fly based on past experience, you can build on the shared wisdom of industry experts to make a great API or client application. on building an API using the OAS standard isn’t out of reach and is something you could begin today! Getting started First Published here

Too Long; Didn't Read

Making security fun one episode at a time

Build delightful APIs using the OpenAPI Specification

Too Long; Didn't Read

Michael

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Build delightful APIs using the OpenAPI Specification

Too Long; Didn't Read

Michael

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES