APIs are the lifeblood of data-driven apps and businesses. And yet, no two services are alike. This has created major headaches in terms of getting APIs to communicate with one another. That’s not to mention the issues it raises about quality, standards, and security. Here’s where OpenAPI comes in. OpenAPI, the industry-standard API specification, has become an essential aspect of an API’s ultimate success.

Connectivity and collaboration are key components of running a successful organization, even if you’re not trying to turn a profit. You want people to be able to find your business or brand. If you’re an API producer, you want people to be able to find — and engage with — your data as well.

OpenAPI is one of the most efficient ways to ensure your data is accessible for as many API consumers as possible. OpenAPI is also firmly in keeping with the original democratic, egalitarian spirit of the Internet, with its utopian vision of high-quality data and information for everybody. Below, we take an in-depth look at OpenAPI — a good introduction for newcomers and a review for seasoned API developers alike.

What Is OpenAPI?

OpenAPI Specification allows you to describe a REST API using a standardized format. It lets you define all of the available endpoints and the operations that are available for a service. It also enables you to describe your API’s authentication methods and pertinent contact info, license, and terms of use.

OpenAPI specifications standardize APIs, making them more universal and interchangeable. This is integral when you’re consuming multiple APIs for an app or product, which is becoming increasingly common. It also creates the possibility for automating documentation generation, SDK generation, listing your API on an API directory, among other perks.

OpenAPI was originally named Swagger — part of a series of open-source tools created by Smartbear. It was developed towards the goal of letting an API describe its own format and contents. You can write OpenAPI specifications using either JSON or YAML. Both are easily readable by machines and humans alike.

What Is OpenAPI Initiative?

Don’t be confused — there’s OpenAPI Specification, which details how to describe APIs, and there is the OpenAPI definition itself. Then there’s the OpenAPI Initiative, a group of forward-thinking developers trying to further the OpenAPI agenda.

Part of the Linux Foundation, the OpenAPI initiative pushes to standardize OpenAPI and related open-source software. Their goal is to implement API standardization as well as provide robust tools for using the standard. It legitimizes the OpenAPI project by ensuring that high-end developers are working on the project. This has made it possible for the OpenAPI specification to be adopted by major companies, such as Capital One, PayPal, and even Google.

How OpenAPI Works

OpenAPI describes an API using a document, or series of documents, which details its structure and contents. OpenAPI documents can be in either JSON or YAML formats. The OAS file is similar to an API schema file.

OAS files can be created from scratch. Or, you can use tools to help you along the way. For example, Smartbear provides many tools to get started:

• Use Swagger Editor to define the OpenAPI variables.
• Use Swagger Codegen to add server implementation easily.
• Use the online version, SwaggerHub, to collaborate on design, develop, and build APIs as a team.
• Finally, use Swagger UI to visualize and document your OAS files. Documentation is critical for showing consumers how to interact with resources.

OpenAPI files can also be generated quickly for existing APIs. There are several Swagger tools for this, as well. Swagger Core generates OAS files for existing APIs using the JAX-RS or node.js frameworks. Swagger Inspector lets you generate an OAS definition for any API endpoint directly from your browser.

Suppose you’re an API consumer wanting to interact with an API that has an OpenAPI specification file. In that case, you can also use the Swagger Inspector or Swagger UI to explore the API, as long as you have the URL for the API’s Swagger definitions. You can then generate a client library.

This is just the tip of the iceberg when it comes to OpenAPI tools, however. Consider the Developer Experience Portal by Apimatic, for instance. It gives you everything from an API explorer to a documentation generator to code generation. The Developer Experience Portal costs a bit, but is relatively inexpensive and worth noting due to its extensive capabilities.

There are plenty of free and open-source OpenAPI tools and resources as well, of course. Consider the suite of services offered by Apicurio, which are web-based tools that let you do everything from designing your own APIs to generating schemas and documentation.

OpenAPI opens the doorway to non-developers and less technically proficient people to use and consume APIs. This will likely usher in a new age of data-driven apps, tools, products, and resources.

Benefits Of OpenAPI

In 2019, writing for Newstack, author John Feeney discusses the necessity of embracing APIs for data-driven businesses that want to remain successful. “Becoming an API producer can offer huge dividends in terms of growth and revenue. For businesses that have truly embraced an API-first strategy, they have created a new go-to-market channel that generates substantial revenues from referrals and usage fees.”

There are many API success stories. Stripe, Twilio, Salesforce, Shopify, and others have become multi-billion dollar companies thanks to adopting an API-first strategy. We’ve also seen a rise in API-driven startups sharking up Silicon Valley. At other companies, APIs have brought indirect benefits to complement the existing business.

By this point, you should be starting to see the benefits of using OpenAPI. APIs are no longer a cottage industry, a niche industry, or a technique for hardcore programmers and developers. APIs are an industry in their own right. That means they need to be accessible and understandable for a broad cross-section of different API consumers, all with differing levels of technical capacities.

Having standards in place for creating and consuming APIs is beneficial for API developers and consumers alike.

Collaborative API Design

APIs are meant to be used. With that in mind, it’s often a mistake for an API to be designed and implemented by only one person. For an API to be as useful as possible, the developer needs to keep the end consumer in mind. OpenAPI specifications inherently ensure that everybody’s on the same page.

The standardized format also means that multiple people can work on the same API. OpenAPI files can be stored in shared directories like GitHub, where they can be easily added to, forked, or cloned. This collaborative approach is excellent for versioning and documenting an API’s history. It’s also ideal for collaborative API-first design, as the standardized nature of OpenAPI makes it possible to generate code from the specification file.

OpenAPI also ensures that documentation stays up-to-date and stays connected to changes happening in the API. These can be enforced using continuous integration processes.

Saves Time And Avoids Error

Using a standardized format means that some development aspects can be automated. Swagger’s Codegen tool can create code around the OpenAPI specification. Codegen can be used to auto-generate code for server implementations, for example. It can even create a whole mock server so the client can try out the API before it’s deployed.

The standardization makes it possible for third-party developers to create similar tools. For example, resources like APIMatic translate an OpenAPI specification into an SDK for whatever development environment you use.

Ensures Quality

Having a uniform format helps standardize your API development process from start to finish. It also helps make it possible to test your API during the development process. You can port OpenAPI definitions into applications like Postman to test the API manually.

Having that specification in place also means that you can test other APIs, as well. This means you can test any additional APIs that you may be using, which further helps ensure any products you create using multiple APIs will be as stable as possible.

Generate Interactive, Appealing Documentation

Even if APIs are going to end up being machine-readable, ultimately, they still need to be understandable by the user. OpenAPI also makes it possible to standardize and automate documentation creation.

Standardized documentation also makes it easier for developers and API consumers to try out an API. Using a sandbox, they can easily send a request from their browser to audition an API without having to write any code of their own.

There is a wide array of API documentation generating tools available using the OpenAPI specification, many of which are open-source. LucyBot lets you generate API documentation as a web page. ReDoc is an open-source API generator that’s available on GitHub.

Standardized documentation also helps give API developers a checklist to consult when they’re creating their APIs. It makes it far less likely that essential API elements won’t be overlooked.

Makes Your API Marketable And Discoverable

If you want your API to be successful, people need to be able to use it. This includes non-programmers and laypeople — especially if you’re developing an API-as-a-product.

Following the OpenAPI specifications means that API consumers can use their preferred tools and resources to explore your API. It also makes it easier to integrate multiple APIs into one application.

Including an OpenAPI file also makes your API more machine-readable. This makes it easier to submit your API to API directories and marketplaces, exposing your service to more developers as they comparison shop. It also makes it easy to submit your API to services like Microsoft Flow, making them consumable for those looking to implement an Integrated Platform as a Service (IPaaS).

OpenAPI Example

We’ll round out our introduction to OpenAPI with a real-world example to help you visualize the format and how you can integrate it into your API development workflow.

This is what an OpenAPI 3.0 specification looks like as a YAML file:

openapi: 3.0.0
info:
  title: Pet Store
  description: API for Pet Store Online Portal.
  version: 0.1.9
servers:
  - url: https://api.example.com/v1
    description: Main API server
  - url: https://staging-api.example.com
    description: Sandboxing server
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Retrieves all of Pet Store's users.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

We’ll unpack this a little bit so you can get an idea of what’s happening.

The first line contains the OpenAPI metadata, detailing what version was used for the creation.

The info section contains all of the basic API information – title, description, and version. version is the current version of your API, not the version of OpenAPI, incidentally, so make sure not to confuse the two.

The server section is where you include the details for your API server. You can include multiple servers, as well, so you can include separate info for production and sandbox environments. The server section will automatically dictate the rest of your API address, also. So if your server address were https://apiexample.example.com/v1, the /user endpoint would be https://apiexample.example.com/v1/USER.

The paths section lays out individual endpoints. It also defines which operation can be used at that endpoint. Operations can be further broken down by using URL path, queries, headers, and cookies.

If an operation sends a request, OpenAPI can also describe the body using the requestBody keyword, which describes the body of the request as well as the types of media it supports.

The response section of the OpenAPI specification details all of the different responses your API can deliver, such as HTTP status codes. This is a new addition to OpenAPI 3.0, incidentally, as it was not required in the previous versions.

The components/schema section lets you dictate common data structures used in your API. These can be referenced using a $ref whenever a schema is required.

Finally, the securitySchemes and security sections lets you describe what kind of authentication is used in your API.

You can read the full OpenAPI 3.0 specifications on GitHub.

OpenAPI: Final Thoughts

Standardizing APIs is an unavoidable necessity. As APIs transition from being a niche interest for passionate data analysts into the data-driven economy’s lifeblood, it will be necessary to ensure that APIs are consumable and discoverable, not to mention interchangeable and secure.

OpenAPI is laying the groundwork for a standardized API framework, similar to standardized parts. Like standardized parts, OpenAPI could open the floodgates on the next Industrial Revolution, while making life easier for developers and API consumers alike.