In my previous post, I had detailed the importance of definition driven development using the OpenAPI Specification (OAS), and promised to follow up with more posts that detailed how the OpenAPI Specification can help various aspects of your API lifecycle.
In this second post in the series, I’ll take a deep dive into understanding just how the OAS can help you in the first stage of your API lifecycle: API design.
What is API Design?
Good design is the reason why monuments become wonders, and why products become great. From monuments to the Eifel Tower, to products like these cool drinking straws, design can be the cornerstone for awesome usability and adoption.
In the world of APIs, design can be thought of as modelling the contract between the server and client. In a previous article, I gave the following definition of API design:
“Designing an API means providing an effective interface that helps your API’s consumers better understand, use and integrate with them while helping you maintain it effectively. Every product needs a usage manual, and your API is no exception.”
Tony Tam, the creator of the original "Swagger" Specification, explains that designing an API involves “planning for failures.” The API contract helps stakeholders, both internal and external, understand what to do, and how they can better work together to build a great API.
Designing the API using OAS 3.0
The OpenAPI Specification is one of the most well-known ways of designing APIs. The OAS specifies the rules and syntax required to describe the API’s interface. At the time of writing this article, we are in the third version of the OAS. The OAS has evolved to meet the needs of modern API teams, and continues to introduce updates to make the specification simpler to use, and easier for humans and computers to understand. This is the general outline of an OAS defined API using OAS 3.0:
The above figure breaks down the various sections in an API contract designed by the OAS. It may look confusing at first, but let me break down what each section means and how it can be used.
Info
The info section contains the meta data associated with the API’s contract. The required parts of this section are the title, version, and description of the API. This section can also have other fields like contact information, license information and terms of service links. Essentially, the Info object should give your consumers as well as your internal developers a high-level overview of what your API does.
openapi: 3.0.0
info:
title: Simple Pet Store
version: 1.0.0
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
name: API Blogger
email: [email protected]
url: http://example.com/support
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
Read the full documentation here.
Servers
Your API is the contract between the consumer and your server. The Server object can give your client information on where the API’s servers are located, through its URL. Unlike the 2.0 version of the spec, which only allowed your API definition to have one server URL, OAS 3.0 supports multiple servers. This is useful since in the real world, APIs exist in multiple environments, and the contract’s business logic may change depending on the environment.
An example of this section is below -
servers:
- url: http://production.example.com/v1
description: Production server
- url: http://staging.example.com
description: Staging server for testing
Read the full documentation here.
Security
Every API in today’s data sensitive world needs some level of security. The OpenAPI description format supports various authentication and authorization schemes to mitigate unknown, unregistered users from accessing the API. The OpenAPI supports:
- HTTP authentication schemes
- API keys in headers, cookies, or query strings
- OAuth2
- OpenID
There are two steps to implementing security in your API design. The first step is defining the security implementations, and the second is calling them. The Security object, defined in this section, is used for calling the actual security definition. Defining the security implementation is done in the Components section, detailed later in the article.
This is an example of the Security object:
security:
- ApiKeyAuth: []
- OAuth2:
- read
- write
components:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
In the above example, the ApiKeyAuth is called under the Security object, though the actual definition of the object should be done under the components object.
Read more about Security objects here.
Paths
This section shows the various end points your API exposes, and the corresponding HTTP methods. It’s also under each method that the actual request-response cycle is detailed. The requests are described by Parameter objects, and the responses by the Responses objects.
You can read more about paths and operations here.
Parameters
Parameters are the variable parts of your request. There are four types of parameters you can specify using the OAS 3.0:
Responses
Responses are the objects returned on a request. Every response is defined by its HTTP status code and the data returned. The HTTP status codes used define whether the request was successful or unsuccessful. To see a list of HTTP status codes, please read here.
Here’s an example of a simple Response:
responses:
200:
description: Successful Response
content:
text/plain:
schema:
type: string
example: Example string is here
Read more about responses here.
Components
As you expose more resources and operations against your API, the contract can tend to get really long. Your API may repeat a lot of existing parameters or response descriptions in many different paths and operations, and rewriting them every time makes them prone to inconsistent descriptions and can be very time consuming.
The component object can hold a set of reusable objects of your API’s design. The reusable objects can be schemas, responses, parameters, examples and more. The exact reusable component can then be referenced in any path item.
Here’s an example of the components object:
paths:
/pet:
get:
summary: Get all pets
responses:
'200':
description: List of all pets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet”
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
example: 65
name:
type: string
example: doggo
age:
type: integer
example: 4
Read more about components here.
External Docs
Any additional information you can offer to ease consumption and integration with your API is always a good idea. OAS 3.0 allows you to reference external documentation.
Description: Additional info can be found here
url: http://info.here.com
Tags
Tags are friendly categories to group various operations. This allows consumers of the API to better segment and identify what they want use the API for. These tags can also be handled by other third party tools which integrate or read the OAS.
Tags can automatically be added to every path operation using the tags object. You can always give a better description to what each of these tags mean by adding an optional tags section in the root level of the API definition.
paths:
/pet/findByStatus:
get:
summary: Finds pets by Status
tags:
- pets
...
/pet:
post:
summary: Adds a new pet to the store
tags:
- pets
...
/store/inventory:
get:
summary: Returns pet inventories
tags:
- store
...
tags:
- name: pets
description: Everything about your Pets
externalDocs:
url: http://docs.my-api.com/pet-operations.html
- name: store
description: Access to Petstore orders
externalDocs:
url: http://docs.my-api.com/store-orders.html
Read more about tags here.
Of course, this is just a general overview of the various sections associated with an OpenAPI designed API. Design is subjective, and while the OAS gives you the required rules and items to describe your API, how you use them to effectively communicate the value of your API is what makes for a great design. I had covered good practices in API design in the past, so do check it out and give me your thoughts.
If you’re looking to learn what’s new in OAS 3.0 when compared to 2.0, check out this recorded training, and if you just want to learn how to get started with the OAS, you can always use this video as a reference.
The Right Tools For API Design
Designing is probably one of the most important aspects of the API lifecycle, and as such, requires a dedicated tool. Swagger’s OpenAPI Editor can be a great way to get started your API design process. It’s clean, efficient, and armed with a number of features to help you design your RESTful interfaces, straight out of the box.
- The Editor works in any development environment, be it locally or in the web
- Validate your syntax for OpenAPI-compliance as you write it with concise feedback and error handling
- Render your API specification visually and interact with your API while still defining it
If you want to get collaborative with your API design, you can always try SwaggerHub. SwaggerHub is a API development platform for teams to design APIs in a consistent and standardized manner. The Swagger tooling ecosystem, combined with the OAS can take your API design game to the next level.
Thanks for reading! Looking for more API resources? Subscribe to the Swagger newsletter. Receive a monthly email with our best API articles, trainings, tutorials, and more. Subscribe