The Pragmatic Approach to RESTful API Design

Have you ever been working in a mobile app and everything seems to be just a little bit off? You click on a button and it takes an extra few seconds to load. Or, the button next to the one you clicked is where the app takes you. Frustrating, right? These problems arise when the user interface design hasn’t been properly developed. Now, imagine you are a developer trying to fix a problem like this and your user interface for changing it doesn’t work. This is whererestful API design comes in.

An API is the user interface for a developer, where they post data and delete bugs. Now, obviously this area is only accessed by developers so it doesn’t have to be beautiful, but it should be very pragmatic and practical. In this article, we are going to walk you through how to create a RESTful API design for your developers that makes it easier for them to do what they need to do efficiently and effectively.

Key requirements for a RESTful API design

There is a lot to be said about RESTful API design online. In fact, if you were to go looking you would find no shortage of opinions on best practices. However, since we are looking at this from a pragmatic perspective, we are only going to focus on a few key requirements. Thanks toVinay Sahni for creating this list.

Your design should use web standards where they make sense.

It should be friendly to the developer and be explorable via a browser address bar.

Make sure it is simple, intuitive and consistent to make adoption not only easy but pleasant.

It should be efficient, while maintaining balance with the other requirements.

Keep these requirements in mind as you work on your RESTful API design to make sure you are doing the most for your developers.

Pragmatic REST APIs

As we look to design with pragmatic ideas in mind, it’s worth looking into exactly what that means. Pragmatists believe that all design trade-offs should be resolved based on concrete, project-specific requirements and constraints. The indiscriminate application of the same design principles and patterns across widely different problems does not seem like disciplined design.

Instead, without the proper requirements and constraints, pragmatists prefer to use the simplest possible design. The context will define exactly what simple means, but it typically means the best fit. Whether that is the best fit within the framework, tools user, or technologies involved depends on the developer, but it should be one of these. By making the RESTful API design as simple as possible we are cutting out work for the devlopers later and trying to make the most efficient system possible.

RESTful URLs and actions

The key principles of REST involve separating your API into logical resources. These resources can then be manipulated using HTTP requests where they each method has a specific meaning. We use such actions such as GET, POST, PATCH, DELETE, and others to tell the API exactly what we need.

When you are doing this, make sure that you make your resources nouns instead of verbs. Along with this, this won’t be a one-time thing. As you continue to grow, this may require some re-mapping and reworking.

Secure everything – Use TLS (SSL)

Regardless of what you are working on with your RESTful API design, you need to constantly be using TLS or SSL to secure everything. In today’s age of working on the go, you can never be too safe with your security. Imagine that you open your laptop at a coffee shop to make some edits and forget to secure your communications. Who knows who might be trying to get into your code?

By always using SSL for everything, you won’t have to worry about this when working outside of a secure network. Additionally, this simplifies authentication efforts for you and your staff. If everyone has a simple access token, you won’t have to worry about signing off on who can use it and who can’t.

RESTful API design documentation

Without proper documentation, even the best API is rendered essentially useless. The docs that you are using should be made accessible and more importantly, searchable. Too often the important information is behind a login wall or must be downloaded in a PDF. This can be frustrating to someone trying to work efficiently.

The pragmatic solution is to release your docs that show complete request/response cycles. Preferably they should be paste-able examples, such as links that can be put into a browser or terminal.

Keep in mind, once you put out a public API, you can’t break things without notice. The documentation must include and deprecation and details surrounding updates to your API. Make sure you have a good avenue for dispersing this info, such a as a blog feed or newsletter.

Versioning your API

Versioning your API will help you to iterate faster and ensure that invalid requests don’t hit updated endpoints. It can also help you to smoothly over any transitions as you can continue to offer old versions for as long as you need.

While there are mixed opinions about where exactly to include the version of your API that you are on, we recommend the header. However, the version should be in the URL if possible to make sure it’s explorable in a browser across all versions.

Final thought

There is so much more to be said about REST, APIs, and pragmatic design, but we do not have the space to do so now. Instead, we just wanted to leave you with some final thoughts on RESTful API design that you should keep in mind.

An API is a constantly changing and evolving thing that is never going to be completely stable. However, it is your job to make sure that these inevitable changes are well managed. Look into what is reasonable for your industry, but well documented and announced multi-month depreciation schedules can be an acceptable practice for many APIs. If you can master the chaos and change ofRESTful API design, you will be in a good place moving forward with your developers.