API Specifications 101: OpenAPI & Beyond Written by: Chris Von See API specifications (machine-readable descriptions of an API’s structure and behavior) can boost API development productivity… if only API publishers would use them. Imagine you’ve been tasked with integrating a new third-party service into your company’s application. You go to the vendor’s developer portal, create an account, and hit the documentation, where you discover reams of text describing everything except how to use their API. There are few API structure details, minimal descriptions of query parameters or payloads, no examples, and no list of possible status codes or their meanings. Sighing, you fire up your favorite API tool and settle in for the long haul. After burning an hour or two trying to authorize your application and invoke the first of the many APIs you need, you can’t help but wonder, “Why did this company make using their API so hard?” You’ve just hit one of the key reasons that API specifications were created. Why are API specifications important? API specification documents solve problems such as the one described above by defining a comprehensive description of an API’s behavior: The API’s “address” (the path) Its input (query parameters and payloads) Its output (the response payloads) How the API can fail and how to fix it Most API documentation has at least some minimal version of these core API documentation elements. An API spec’s machine-readable nature means that it can be used to auto-generate human-readable documentation, which in turn supports documentation standards by verifying that all of the information developers need is present. Incorporating automatic API documentation generation and validation ensures that your documentation is always complete and up to date. It gets better: readily available (and, in many cases, programming language-specific) tooling that leverages API specs can create “playgrounds” for your API right inside your documentation. A playground with automatically retrieved API keys or access tokens allows you to: Read about an API Enter API parameters and payloads Make the call and immediately see the result Iterate until you get the needed output. This type of “rapid learning” tool—enabled by the API specification document—saves time and effort for both internal and external developers, making your service one that developers love to use. The OpenAPI Specification (OAS) Many API specification standards have come and gone over time, but the OpenAPI Specification (also known as OAS) is far and away the most popular standard for REST APIs. Since its creation, OAS has beaten out other competing standards such as RAML and API Blueprint. Its tool ecosystem has expanded to support developers and technical writers across the entire API lifecycle. OAS provides a well-defined taxonomy (and extension mechanisms) that provide structure and standardized meaning to the various elements of an API description. openapi: 3.0.2servers: – url: /v3info: description: |- This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about Swagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we’ve switched to the design first approach! You can now help us improve the API whether it’s by making changes to the definition itself or to the code. That way, with time, we can improve the API in general, and expose some of the new features in OAS3. Some useful links: – [The Pet Store repository](https://github.com/swagger-api/swagger-petstore) – [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) version: 1.0.20-SNAPSHOT title: Swagger Petstore – OpenAPI 3.0 termsOfService: ‘http://swagger.io/terms/’ contact: email: [email protected] license: name: Apache 2.0 url: ‘http://www.apache.org/licenses/LICENSE-2.0.html’tags: – name: pet description: Everything about your Pets externalDocs: description: Find out more url: ‘http://swagger.io’ – name: store description: Access to Petstore orders externalDocs: description: Find out more about our store url: ‘http://swagger.io’ – name: user description: Operations about userpaths: /pet: post: tags: – pet summary: Add a new pet to the store description: Add a new pet to the store operationId: addPet responses: ‘200’: description: Successful operation content: application/xml: schema: $ref: ‘#/components/schemas/Pet’ application/json: schema: $ref: ‘#/components/schemas/Pet’ ‘405’: description: Invalid input security: – petstore_auth: – ‘write:pets’ – ‘read:pets’ requestBody: description: Create a new pet in the store required: true content: application/json: schema: $ref: ‘#/components/schemas/Pet’ application/xml: schema: $ref: ‘#/components/schemas/Pet’ application/x-www-form-urlencoded: schema: $ref: ‘#/components/schemas/Pet’ An example of an OpenAPI specification written in YAML, and a documentation page generated from that specification using ReadMe. While it was once necessary to create these specification documents manually, it’s now possible to create and manage API specification documents directly from your code, using tools such as falcon-apispec (for Python) or springdoc-openapi (for Java). Learn more about ReadMe’s approach to using these tools in our guide to generating an OpenAPI description. When you generate a specification in this way, you can then manually augment it with additional material if needed. As time went on, more tools joined the OAS ecosystem to address additional parts of the software development lifecycle: Optic can help ensure the quality of your API by detecting breaking changes and validating your API implementation against the specification during the build/test cycle. Services such as ReadMe make managing documentation versions easier by importing API specifications, combining them with human-generated documentation, and producing high-quality output. ReadMe also enables “playground” behavior directly in the documentation, produces API developer portals, and fosters community around your API by creating integration discussion forums. AWS’s API Gateway can now leverage OAS specifications to create gateway API definitions. Similar capabilities are available for other API gateways, such as Apigee, Kong, and Azure API Gateway. A number of tools are available that can be used to generate SDKs, create mock servers, and produce server-side API frameworks in many different languages. SDK generation in particular can be valuable because it reduces the complexity of using your API and helps hide variations in API versions. Combining the output of these tools with additional material produced by technical writers can enable your development team to produce the API of your dreams. Incorporating API specifications into your development lifecycle The process of implementing OAS specifications in your software development lifecycle and reaping the benefits is fairly straightforward. First, decide how to create the specification itself. Should you generate it from the code? Or make it an independent artifact as proposed by the API-first approach? The correct approach will ultimately depend on how your team is structured and how rapidly your API changes. Smaller companies may want to start small, build the base specification from the code, and add to it over time. Larger companies with more resources may choose to dedicate a team to managing this artifact independent of the code. Don’t forget to consider the elements that take your documentation to the next level, such as suggestions for fixing errors by error code and language-specific code samples. Make the documentation publication process part of your software build/deploy process. Tools that can integrate via Github actions (or their equivalents for other continuous integration tools such as Travis CI or Gitlab) make the process of publishing quality documentation during deployment simple and effective. Add additional tooling to your build/deploy pipeline to take additional advantage of your API specification efforts. For example, validating that the API matches the published spec and your documentation can be invaluable. Consider creating SDKs from your spec. SDKs can remove some of the complexity of API usage by putting a “friendlier” face on APIs and helping to manage API version-related changes. As your API specification matures you can evaluate how additional parts of the OAS ecosystem can help your process. Making the magic happen Every organization’s software development process is different, and it takes time to find the right tools and technologies to suit your specific needs. However, there’s an easy way to get started that pays big dividends: produce API documentation that embodies the “show rather than tell” approach. ReadMe leverages API specifications to produce developer-friendly documentation with all the features needed to guarantee success with your APIs. In addition, ReadMe provides developer dashboards, community management support features, and easy integration with developer workflows. These strong documentation management, community, and SDLC integration capabilities accelerate API adoption, making your product a joy to use!