We recently conducted an Akamai Developer webinar where we demonstrated the functionality of the new Akamai API Gateway. During that session, we polled participants with this question: “Are you using an API definition language, and if so, which one?” Of the respondents, 41% said they were NOT using a definition language while 58% said they were using Swagger 2.0. Put differently, there were almost as many people not using an API definition language as those using the most dominant one. That told me we have work to do, because we believe that API definition languages provide significant benefit to developers.
What is an API definition language?
Put simply, an API definition language is like a blueprint for a house—but for your API. Before you pour concrete or hammer a nail to build a house, you create a plan to guide those efforts. API definitions function in exactly the same way. Definitions are a set of rules to semantically describe the structure of an API. These rules are written in human-readable (YAML) and machine-readable (JSON) formats to ensure they can be both understood and processed.
Developers build API definition files for a multitude of reasons:
- To create documentation for their APIs
- To share API data internally or externally without sharing the actual code
- To help others onboard and use APIs quickly
How Swagger helps developers
Integrating a new API into your application can be troublesome and difficult. REST semantics can vary wildly by the vendor producing them and the language the vendor uses to write them.
Without an API definition language such as Swagger, developers must spend a great deal of time making trial-and-error requests as they experiment with an API to discover how it works. Swagger eliminates that unnecessary toil by making the functionality of the API explicit and easy to understand.
Swagger also makes your coding work easier as well. Once you have a Swagger blueprint built, you can reference back to it as you code your API. For example, in Figure 1 below you can see a Swagger file for a commonly used example API called “Swagger Pet Store” in Swagger format. In Figure 2 is the Node.js implementation of that same Swagger file. Note that the functions defined in the Swagger file are also present in the Node code: the ability to add a pet, delete a pet, find a pet, etc.
Swagger files can be built from scratch using nothing more than a text editor. If you want a more advanced tool, SmartBear offers a free editor that you can download and run locally or online here and it looks like this:
The benefits of using the SmartBear Swagger Editor is that as you type directives into the left-hand pane to craft your Swagger file, your code is evaluated against the Swagger spec itself. Any syntax errors you might make are surfaced as errors in the right-hand pane of the editor. Your Swagger file must comply with the Swagger specification on Github to be parsed properly. You can read all the details of the spec on Github.
Swagger files are naturally decomposed into sections for easy readability (see figure below). The first section of any Swagger file can be considered metadata (“data about data”) about the API itself. Fields in this section include items such as the title of the API, a description of what it does, and its unique version number. This section also contains global settings that apply to the whole API, such as the hostname used and the basepath.
The next section provides details about each API request in turn. In this section you will find the HTTP verb in use, summary text of what the resource does, the parameters that the request takes, and the form of the response delivered and what it contains. This data is then repeated for every verb for the resource.
In addition to showing the details of requests and responses, Swagger files can also detail error responses and even link out to child Swagger files that contain even more detail.
One of the best ways to learn how to construct a Swagger file is to review Swagger files others have published and then deconstruct them. To do this, first review the Swagger file against the specification to understand what all the directives mean. Then open the Swagger file in the SmartBear editor, and try changing some of the existing settings, one at a time. For example, delete the Swagger version number and see what error message pops up. Replace it, then try deleting another element, and review that error.
Github is a rich source of publicly-available Swagger files for your education/deconstruction needs:
- Lufthansa Partner API
- New York Times public API
- Box Open API specification
- American Airlines mock engine
We hope this helps you get started with Swagger, so you can reap the tremendous benefits that Swagger brings developers every day. When you’re ready to start using Swagger files to onboard your APIs to Akamai API Gateway, go to the API Gateway home page and scroll down to “Getting started: Onboard your API now”, then follow the steps listed there.
Jeff Costa is a senior product manager at Akamai Technologies.