API definitions are structured data files that provide critical information about how APIs are supposed to work and how they are organized. Unlike API specifications designed for human readability, these files are intended to be machine-readable. API definitions typically include request format requirements, protocols used, and naming conventions for endpoints. Since the files themselves are simply structured text and not directly executable, they can work with any programming language.
When used wisely, API definitions can work hand-in-hand with existing development tools for generating artifacts such as human-readable documentation, boilerplate code, and test cases. Read on to learn more about how API definitions work and how you can seamlessly integrate them into any phase of your development process.
API Definitions: Benefits and Tools
If you haven’t worked with API definitions before, you might wonder why you should bother -especially when creating them adds a bit of time upfront to the development process. This section outlines the key benefits of creating API definitions and discusses some popular approaches for doing so.
Why create API definitions?
One simple reason for creating API definitions is that it might be necessary in order to work with certain common platforms on the market. For example, if you work with API gateways from Google Cloud, Azure, Apigee, or Amazon, you need to have API definitions in place before your APIs can go live on those platforms. All four of these platforms support the popular OpenAPI Specification, which we will discuss in more depth shortly.
While compatibility with industry-standard platforms is one good reason to adopt API definitions, it’s far from the only reason. In recent years, many development teams have embraced a design-first approach. If your team is among them, API definitions are a no-brainer. Not only do they force you to think about the intended design and function of your API, but they also work with many automated implementation tools.
Some of the tasks that API definitions can help with include automatic SDK and documentation generation, as well as mock server instances to test your interfaces. With these use cases, API definitions can serve as points of reference for future documentation.
Another benefit of API definitions is that they can help you spot logical errors in your code relatively early, especially when you use validation tools. Errors spotted at this stage are much easier to correct than those you encounter later on. An IBM study reports that errors found after a product’s release cost four to five times as much to fix than errors found during the design process.
A less obvious but just as important benefit of API definitions is ensuring consistent design approaches across different teams. Adding API definitions for existing code offers the additional benefit of reducing the time it takes a developer to get up to speed when they change teams within the organization, as the documentation will already be in place.
What are the options for API definitions?
The most common standard for API definitions is the OpenAPI Specification, mentioned earlier. Given its widespread adoption, it makes sense to explore this approach in greater detail.
The idea behind OpenAPI is to carry information throughout the API lifecycle. Since files are usually written in YAML or JSON, they can easily be shared among code bases working with different frameworks and different languages. This means that consumers of your API do not have to learn the ins and outs of your chosen programming language to use the API.
At the very least, OpenAPI definition files must include important details such as the version of the OpenAPI standard being used, metadata that identifies the API, including its name, description, and version, relevant server endpoints, and the allowable operations on those endpoints. The OpenAPI Specification also offers space for information about servers, security systems, reusable objects, tags, and more. As is typical in structured text files, information can be nested as required in API definitions.
Although API definitions themselves are text files, that doesn’t mean you’re limited to simple text editors when it comes to creating them. It can be helpful to have a visual model of your approach, as well as robust development features like syntax checking and autocomplete. Stoplight Platform includes a visual editor to create OpenAPI definitions, as well as other related files. SoapUI is another tool that allows you to automatically generate things like test cases and mock servers from API definitions.
However, you may have constraints that mean OpenAPI is not the right fit for your needs. The good news is that you have other possible choices. For example, if you’re heavily invested in GraphQL, you can create API definitions for it using JSON or GraphQL SDL. Tools also exist for popular formats such as MuleSoft’s RAML and Google’s protobuf.
API Definitions Help at Any Stage of Development
Ideally, as with most design methods, you’ll want to bring in API definitions as early in your development process as possible. But that doesn’t mean that all is lost if you’ve already started development work, or even if you already have a product on the market. This section offers suggestions for how to incorporate API definitions regardless of where you find yourself in the development process.
Create a new API design-first and definition-first.
When it comes to a design-first approach, we tend to think of the needs of human users, and we should always keep them in mind. But a lot of code interactions never reach humans, and it’s important to understand how we manage that communication between machines. Understanding how to get the best possible use of automated tools is a key element of creating API definitions.
If you already have plenty of experience working with a design-first mindset, or you’re the type of person who likes to dive in at the deep end, you might consider a schema-first design. One of the biggest drawbacks of ad hoc API design is the need to verify everything whenever any changes occur in the API, be it the addition of features or the implementation of a new server. Making these changes manually is a labor-intensive and error-prone process. Incorporating the same information in an API definition enables you to work with automated tools that handle these updates for you.
Creating your definition files at the same time as your design specifications can even help you elicit and refine your system requirements. Following standards such as the OpenAPI Specification allow you to do this in a way that’s both platform and language-agnostic.
Capture a snapshot of where you are now.
Even if you’ve already started development work, API definitions can still be helpful. One of the most important benefits of incorporating API definitions at this particular stage is that it can help determine whether the code you’ve already written aligns with how you wish to continue building your product. If that turns out to be the case, great! But even if you find problems in your code at this stage, fixing them now is significantly easier than doing so in later stages of development.
Fortunately, there are several tools that can save you time on this task. One such tool is RedHat’s API Designer, which is especially useful if you’re already working with their OpenShift services. Another option is IBM’s API Connect, which can help you create definitions for both REST and SOAP APIs. Both tools provide graphical interfaces and can create definitions according to the OpenAPI Specification.
Create a definition from an existing API.
While it’s true that API definitions are best suited to being introduced during the design process, that doesn’t mean that APIs that have already been released can’t benefit from definitions. As mentioned earlier, if you want your API to work with the most popular API gateways, establishing a definition will be necessary.
But even if you’re not looking to deploy your API on one of the major platforms, it can still be a good idea to set up a definition for your API. For example, if you’re aiming for greater company-wide consistency with your code base, it makes sense to create definitions for existing APIs to ensure that they are in line with the code standards you intend to uphold, as discussed previously. If there is a gap between where your code is and where you want it to be, creating API definitions can help you nudge development in the direction that you want it to go. Tools like Spectral can help you ensure that your definitions conform to both OpenAPI requirements and your organization’s internal design goals.
Take the Next Step
Now that you have a better understanding of the benefits of API definitions and how to work with them, what’s the next step? Tools like Stoplight Platform can help you create API definitions that work together with automated artifact generators to speed up documentation and code generation, especially when you adopt a design-first approach. Get started by creating your first Stoplight workspace today!
