DEV Community: Stoplight

API Design Patterns for REST Web Services

Adam DuVander — Mon, 08 Jun 2020 20:57:12 +0000

REST turns 20 years old this year. In addition to the architecture and recommendations outlined in Roy Fielding’s dissertation, we now have two decades of practical application. When designing APIs, it makes sense to build upon the best practices already implemented by countless others.

This post identifies the most common REST API design patterns across several categories. Rather than start anew, build upon this foundation of API guidelines from thousands of successful API companies.

HTTP Methods and Status Codes

By the strict definition of REST, you don’t need to use the HTTP protocol. However, the two developed alongside each other, and almost every RESTful API relies upon HTTP. For that reason, it makes sense to structure your API around the built-in methods and status codes that are already well-defined in HTTP.

Each HTTP request includes a method, sometimes called “HTTP verbs,” that provides a lot of context for each call. Here’s a look at the most common HTTP methods:

GET: read data from your API
POST: add new data to your API
PUT: update existing data with your API
PATCH: updates a subset of existing data with your API
DELETE: remove data (usually a single resource) from your API

As you design your API, you’ll want to rely on the methods to express the primary purpose of a call. For that reason, you don’t want to use a POST to simply retrieve data. Nor would you want a GET to create or remove data.

Much as these methods provide the request context from client to server, HTTP status codes help describe the response in the reverse direction.

Some common HTTP status codes include:

200: Successful request, often a GET
201: Successful request after a create, usually a POST
204: Successful request with no content returned, usually a PUT or PATCH
301: Permanently redirect to another endpoint
400: Bad request (client should modify the request)
401: Unauthorized, credentials not recognized
403: Forbidden, credentials accepted but don’t have permission
404: Not found, the resource does not exist
410: Gone, the resource previously existed but does not now
429: Too many requests, used for rate limiting and should include retry headers
500: Server error, generic and worth looking at other 500-level errors instead
503: Service unavailable, another where retry headers are useful

There are many more HTTP status codes and methods to consider, but the above lists should get you well on your way for most APIs.

Use Friendly Endpoint Names

A typical design pattern with REST APIs is to build your endpoints around resources. These are the “nouns” to HTTP method verbs. Your API design will be much easier to understand if these names are descriptive.

For example, if you’re working on a cookbook API, you might include the following endpoint:
/recipes/

As you add new recipes, you would POST them to the endpoint. To get a list, you use the GET method on the same endpoint. To retrieve a specific recipe, you could call it by its identifier in the URL:
/recipes/42

One thing to specifically avoid with friendly REST endpoint names is describing actions. For example, a verb within the endpoint (i.e., /getRecipes/) would run counter to relying on HTTP to provide that context.

Our CRUD API Design Recommendations goes into more detail, including popular topics like plurals and versioning.

Support Use Cases with API Parameters

Naive or simplistic API design can follow all the guidelines above and still not support the use cases that developers will need. It’s important to thoroughly understand how an API will be used and get feedback from collaborators, such as with mock API servers.

Often, when use cases are discovered after an API is built, engineers will create new endpoints to support these unearthed requirements. For example, your cookbook API may need to return only recipes from a specific category, or you want to show the recipes with the least prep time. Rather than create redundant endpoints, plan for smart parameters from the start.

There are three common types of parameters to consider for your API:

Filtering: Return only results that match a filter by using field names as parameters. For example: /recipes/?category=Cookies
Pagination: Don’t overload clients and servers by providing everything. Instead, set a limit and provide prev and next links in your response. Example: /recipes/?limit=100&page=3
Sorting: Provide a way to sort or some use cases will still require paging through all results to find what’s needed. Example: /recipes/?sort=prep_time

These three approaches can be used together to support very specific queries. For example, this API request would retrieve one cookie recipe with the shortest preparation time: /recipes/?category=Cookies&sort=prep_time&limit=1

In some cases, you’ll need additional parameters or a special syntax to fully support API consumer expectations. You will likely want to provide a sort direction (i.e., order=desc or sort=prep_time:asc), and may have times when you want to filter or sort by multiple fields. Understanding your use cases will help determine the complexity of your parameters.

Borrow From Existing Conventions

While this post does its best to cover overall API design patterns, you’ll want to look at standards and conventions specific to your industry or a specific feature. Very few of us are building completely unique APIs, so there is a lot to learn from others.

Many API standards are built around REST APIs. When you implement authentication for your API, for example, don’t blaze a new trail. There are many options, including the well-trod OAuth path, when providing user-associated data. You’ll find standards for API headers and a handful around data formats like JSON and XML, among others.

You may be designing microservices APIs, which has its own set of considerations. Everything covered in this post likely still applies, but you’ll want to pay extra careful attention when designing microservices. Each will need to make sense on its own, yet benefit from a combination (loose coupling).

On the other hand, open banking APIs require their own treatment. European standards are the most mature and have a set of design patterns based around those regulations.

Your industry may have its own set of standards or conventions. Even if they aren’t as strict as banking regulations, it’s worth giving proper consideration to a pattern with which developers will already be familiar.

Document with An OpenAPI Definition

As you design your API, it will be extremely useful to maintain an OpenAPI definition as the source of truth. This format, the next generation of the older Swagger file, describes endpoints, request data, responses, error codes, and more. In addition, it can be used to automate with tooling across the API lifecycle.

Perhaps the most common use of an OpenAPI document is to generate API documentation, especially an API reference. Since the format outlines the ways an API can be called, it contains all the information a developer needs to integrate with the API. Plus, some API references don’t include essential details like error codes, so OpenAPI encourages accurate documentation. Further, you can generate new docs every time your API changes, so they’ll always be up-to-date.

You can also use your OpenAPI definition to create mock HTTP servers, which allows you to try out your API before you write any code. Circulate the interface amongst your team for early feedback, or validate the requests from your API client.

Those are just two potential uses for your machine-readable API definition, which you can create OpenAPI definition files using YAML or JSON. Or, create them much faster with a visual OpenAPI editor. Stoplight Studio can read existing OpenAPI files from any git repo, and you can make edits—or start from scratch—within a beautiful editing environment.

Use Style Guides for Consistency

Some design patterns are a matter of preference. Ideally, you can codify your organization’s approach once, rather than revisiting it each time you create an API. A style guide can keep your company on the same page with API design. In addition to being consistent between APIs, it’s even more important to maintain consistency within a single API.

Some organizations will create a written API style guide. A document that is easily accessible within your intranet helps everyone understand the design patterns you’ve already adopted. However, you can go even farther by enforcing your style guide programmatically. Using a tool like an open source linter, you can define rulesets for your OpenAPI documents.

When you automate your API style guide, you can look for any number of API characteristics: resource and field names, capitalization formats, how you use punctuation, and versioning, among others.

Your style guide, whether written or programmatic, becomes your own guidelines for the design patterns covered here. Help ensure your organization uses HTTP methods correctly, returns appropriate status codes, implements friendly endpoint names, uses smart parameters, and borrows from the existing conventions you’ve already identified.

Now you’re ready to create fantastic APIs, so join the world’s leading API-first companies on Stoplight’s API design management platform.

API Development Demystified

Adam DuVander — Mon, 23 Mar 2020 15:04:11 +0000

It’s clear that APIs are an important part of modern software. Companies frequently develop APIs to share data, functionality, and business processes. However, it’s not always clear where the backend API development ends and work begins on the website, app, or other clients to use the API.

In fact, the most efficient organizations don’t require such a distinct hand-off. When your APIs are built thoughtfully, teams can work in parallel. In this post, we’ll look at the benefits of a forward-thinking API approach and how it is impacted across the full lifecycle.

Why Build APIs?

It’s important to remember the benefits that APIs provide for enterprises. The alternative is large, all-knowing applications, which are slow to develop. In many cases, teams duplicate efforts, because there is not a method to communicate that a problem has already been solved elsewhere. This lack of knowledge limits a company’s ability to work with external parties, as well.

APIs enable collaboration at all levels. A simple example is the interaction between frontend and backend teams. With an interface defined, neither team needs to wait on the other’s work. Rather than sequential efforts, they can work simultaneously. And, in true collaboration, the process can be iterative, sharing what they’ve learned to inform the next version. The same approach works within departments, across business units, and with partner companies.

You can also stop reinventing the wheel. When an API already exists, teams can build upon others’ work. For example, an API to access a customer’s account details could be useful for a website, a mobile app, and many other consumers. With appropriate permissions controls in place, the same API could even be used in a partner’s application.

Indeed, empowering partnerships is a major benefit to public APIs. However, internal API development can even enable external collaboration. Once you make internal teams aware of an API, they may see opportunities with partner companies.

The API Lifecycle

Depending on the terminology you use, API development may refer to the entire lifecycle of an API or one phase within it. Either way, you’ll want to understand each phase and how they work together. While APIs help you move faster as an organization, that doesn’t mean you should create APIs without a thoughtful process. Plus, even hurried APIs will go through the API lifecycle, possibly with more headaches along the way.

Gartner defines the API development process as three major phases: Design, Build, and Run. Too often, teams will think of API development as only the build phase. It’s a natural misconception because that’s when the bulk of the code is written. However, that skips over the important design phase. There’s a lot more than code that goes into developing an API for the long term.

As discussed in testing across your API lifecycle, there are three other important phases: Maintain, Support, and Update. While not necessarily sequential, every API will need these additional phases after it is pushed to production.

As you look to update an API, you end up back where any API development should start: with API design.

Design-First API Development

In the API design guide we discuss the “design-second oxymoron.” It’s during the design phase that important decisions are made about how your API works and what it makes possible. Good API development practices will start with a collaborative design phase.

When designing an API, you’ll need to keep teams on the same page about the decisions you make. The industry has rallied around the OpenAPI specification as a way to detail REST APIs. Sometimes referred to by the outdated term Swagger, OpenAPI is a document format to describe API endpoints and their related data.

Stoplight Studio is a visual API design editor, which helps you quickly produce OpenAPI documents without memorizing syntax or writing any code. By describing an API during the design phase, teams can make important decisions about reusable data models, which HTTP methods to support, and how to handle error conditions.

OpenAPI is a machine-readable format that can help you in the later phases of your API development, as well. As you build your API, you can generate mock servers using your OpenAPI document as the source of truth for decisions made during design. These definitions can also create documentation and serve as a central object when discussing updates to your APIs.

Get started with API design and create your first OpenAPI document or start with an existing repository. You’ll build and run better APIs as a result.

♻️ This post was originally posted on the Stoplight Blog