I have been building APIs for almost a decade now. Over that time, I have learned some solid do’s and don’ts that I now swear by. Building APIs is relatively easy, right? We build out our data model, wrap it in a framework in a programming language we know, then provide simple CRUD wrappers for each resource and call it a day. However, building a good API is a lot harder than that.

When building your API, you need to consider who you are making your API for. It isn’t always just another backend developer who understands and can debug things easily as they are used to it. Your API might be used by a wide variety of people, all with different skill sets and varying levels of patience for an API that doesn’t just work. And ideally, none of these folks should feel pain while working with your API.

With that in mind, let’s talk about the ten REST commandments. There are a set of rules or guidelines that I like to follow to make sure that I am building an API that I can be proud of and that users won’t hate integrating with.

1. Be Practical

What do I mean by this? Modern applications use json, it is a fact. Yes there is still a place for xml in the modern web, but perhaps not in the API space. Ensure you set the headers for Accept and Content-Type to application/json. Formats such as text/html, application/xml, x-www-form-urlencoded, and form-data have their place, but typically not in an API. Yes, if you are building an API that needs an image upload or provides an embed endpoint, that is fine, but as a general rule — use a modern format. It is more lightweight, easier to use, and easy to read!

2. Be Methodical

There are five main HTTP verbs you can use for a reason: use them correctly. If you are trying to fetch information, use GET. If you want to create a new resource on your API, use POST. Use PATCH and PUT in the correct order for updating resources, depending on if you are updating a field or all the fields. Use DELETE to remove a resource too. I have seen many APIs that use either GET or POST for everything and it triggers me more than I would like to admit. Use. HTTP. Verbs. Correctly.

3. Be Semantical

So, what do I mean by this? Let’s take an example of retrieving a list of users from an API. We have all seen or used APIs that will ask you to make a GET request to an endpoint such as /listAllUsers — I mean, this was a standard back in the day. But, it is 2023, and we build REST APIs now. Part of the REST standard is to use pluralized resources with the correct HTTP verbs. Why we still see API endpoints that don’t follow these guidelines I cannot understand. REST is well-documented, easy to follow, and logical.

4. Be Secure

Let’s be honest for a moment. If you aren’t following these practices around security, you should turn your API off now to save you issues. The first thing you need to do is use https because it is easy to set up, install, and use. With free certificates from LetsEncrypt, there is no excuse not to add an SSL certificate to your API these days.

Also, ensure your API implements a level of authorization. It isn’t enough just to authenticate users these days. People will try to access resources or update resources they don’t own. You need to protect against this. Using role-based access control (RBAC) is the bare minimum you should be looking at. Another good tip is to leverage uuid over a sequential ID or identifier. Using something sequential is easy to guess, and potential attackers will notice this quickly and start cycling through URIs to see what they can access that they shouldn’t.

Serverless technologies are generally available. Use them! With serverless technologies, you lose the problems typically associated with servers and security. Servers and even serverless technologies set a certain amount of headers by default, and cleaning up these headers can help secure your API from an information perspective. Technologies such as NGINX and Apache expose the technology and version used on your API by default, which signals to a potential attacker where to look for possible vulnerabilities. Obfuscating this information doesn’t prevent these vulnerabilities, but it does hide the signpost that an attacker might look for.

Updates, updates, updates. To be secure, you also need to make sure you stay on top of patch requests and RFCs that are released. Using a modern framework helps here, as the community or team will be on top of this for you.

5. Be Consistent

Consistency is key in an API. I know I have used APIs in the past that are not consistent, and it is painful! It makes the API harder to work with, and we end up having to add so much messy logic in our applications just to support the API integration. Be kind to your users by having a consistent response, make sure it is documented, and always communicate potential changes to this consistency. Your users are the ones supporting your platform. If you aren’t nice to them, they will look for alternative APIs they can use.

6. Be Organized

API versioning. It is important. It protects your users from potential breaking changes. It stops that “quick update” from having cascading problems across your users. There are, of course, ways you can get away without versioning, but it relies on developers paying close attention to your communications. If you have a strong and very active community that listens to every update you post, sure, skip the versioning and use things such as the Sunset header. But can you guarantee that your community will pay attention to this header? Will they read that email or tweet that you posted? Don’t risk it.

7. Be Graceful

We are human, and we make mistakes. Things will fail. There is no question about it. Failures are fine, believe it or not. It is how we handle these failures that matters most. Having consistent, understandable failure messages, using the right HTTP status codes, and documenting the potential failures people may face is essential to avoid annoying your users. You want to protect your systems while giving enough information to your users so they can handle errors while integrating with your system.

8. Be Smart

APIs are the brain of the whole operation for your application, platform, or product. You need to protect your most valuable asset, the database. Your API shouldn’t just be a map of your database as is. Your API will be running some complex processes — make sure this is easy to do and doesn’t rely on input from your users integrating. They don’t want to have to send several API requests to do one thing. Optimize the API experience that your users will have across multiple platforms. Consider each platform as equal, no matter what the metrics tell you. Metrics can change quickly and without notice. Take all control that the client may have and have it run in the API. Clients should just be leveraging your processes, not running them manually.

9. Be Lean

Speed. I am speed. Sorry, I thought I was Lightning McQueen for a second, about to win the Piston Cup. Speed starts at the database. Optimize your database and use the right database for the job. Next, index and cache the queries where you can. A slow database means a slow application means a slow API means a frustrated user. The less data you send, the faster the response will be. On that note, using a standard like JSON:API or HAL allows you to leverage query parameters to request additional data. Don’t just send it all at once!

There are a few other main ways you can speed it up further. One way is the Content-Encoding of your response. Using something like gzip really helps minimize the size of the response to send it even faster. Cache as much as you can as often as you can, and have a good caching strategy. Cached data is faster to access, making your API faster to respond, making your users happier. It isn’t like a website where you want users to engage with the page for as long as possible. You want your users to go away as quickly as possible with what they need.

Using a more modern HTTP protocol such as HTTP2 or HTTP3 allows you to respond better and use bi-directional transfers instead of a single communication thread. Not to mention all the other amazing features the newer protocol versions offer. Pay-to-win, some things will cost money. You can’t avoid it. For example, services such as Cloudflare and Fastly are paid products, but they are worth their weight in gold. They do so much at the networking level that would just be time-consuming for you. Use them, thank them, pay them.

10. Be Considerate

Building APIs can be quite lonely at times. It’s often just you and your code editor of choice. Even Copilot isn’t that fun to talk to. Yes, you could get a soft plushie or a rubber duck, but it is still just you and your code. Yet, there are a lot of people counting on you to do an excellent job of building your API. All of those potential users and current users want to use your product. But, they want it to work. Therefore, considering the overall developer experience and having empathy for the user journey is essential.

Final Thoughts

So, these are the ten REST commandments that my team is often talking about. They can be summed up as logical or obvious. But, after working at an API observability platform for years, I’ve realized they’re not as apparent as you or I may assume. APIs are meant to be fast, consistent, and reliable. So, I encourage you to consider these points the next time you build or maintain an API.