Best Practices for a RESTful API

Best Practices for a RESTful API

by | 3 min read
Published:
Updated:

Nowadays the web is powered by APIs. With applications being used on desktop and mobile, APIs are essential in allowing the code in backend systems to be reused. The most popular APIs from companies such as Facebook, Google, and Twitter use the RESTful API pattern.

Unlike other parts of your website or app, your API should be designed to be used by programmers, like you. If you have ever used a badly designed API you will know how frustrating it can be to try and integrate with it. So what are some things you can do to make a good RESTful API?

1. Documentation

Yes, I am going to start here. It is the bane of most programmers’ existence. You don’t want to be writing documentation, you want to be coding the next feature. But have you ever tried using an API without documentation? It is a pain! Your documentation should clearly show what your API does and how you can use it. If it doesn’t, no one is going to want to use your API. A good example of good API documentation is Stripe, after all, it is their business to get people to use their API. What I like about their documentation, is it gives great code examples showing exactly how to get started with it in multiple languages.

2. Only use nouns, not verbs

REST is built around the HTTP methods GET, POST, PUT, PATCH, and DELETE. There is therefore no need to include verbs in your API. Your API should be like this:

GET /employees – retrieve a list of employees

Not this

GET /getEmployees

It is also generally expected that you use the plural of the nouns in your endpoints.

3. SSL Everywhere

If you have a need for an API it’s because you are exposing data and actions on that data. Chances are, some form of authentication will be needed and therefore the user will need to send an API key or credentials with each request. This might be token authentication or OAuth. You should therefore always use SSL on your API as it could be accessed from anywhere and you don’t know how secure the users location is. It is also important not to redirect to SSL from HTTP, just throw an error. If you redirect then you are letting clients send data to an unencrypted endpoint!

4. Make use of error codes

HTTP comes with a full range of error codes, good RESTful APIs make use of them. Wikipedia has a good list of error codes and their meanings. It should be possible to find an error code that describes your error and it will be more useful for developers using your API than a 500 internal error.

5. Versioning

The jury is still out on what the correct way is to implement versioning. Some prefer versioning in the URL and others in the headers. Either way your API should always be versioned with any changes you make. Personally I prefer versioning in the URL such as:

/api/v1/employees

You might consider including an unversioned endpoint but this is generally a bad idea. Facebook for example returns an error if you try and use an unversioned API

6. Serialisation

Even though JSON is the preferred output format, you may still need to support XML depending on the clients that will be using your API. I personally prefer doing this using accept headers but it can be done by appending an .json or .xml extension. You might even want to support both methods.

In summary, have a look at some the documentation for the popular APIs and try and follow some of their good points. If you want other developers to use your API, you need to think of them when designing it.

What do you think makes a good API? I would love to here your ideas in the comments below.


🙏 Was this helpful? If you want to say thanks, I love coffee ☕️ , any support is appreciated.


ALSO ON ALEXHYETT.COM

Idempotency - What it is and How to Implement it

Idempotency - What it is and How to Implement it

  • 22 September 2023
When designing an API it is easy to think about the happy path of our applications but if you want to build a robust application and keep…
5 Design Patterns That Are ACTUALLY Used By Developers

5 Design Patterns That Are ACTUALLY Used By Developers

  • 08 September 2023
High-level programming languages have been around since the 1950s and since then programmers worldwide have been using code to solve all…
Domain-Driven Design: Simple Explanation

Domain-Driven Design: Simple Explanation

  • 28 April 2023
When you are trying to build complex software it is important that everyone is on the same page. Even though most of us prefer to work alone…
Monolithic vs Microservice Architecture - Which Should You Use?

Monolithic vs Microservice Architecture - Which Should You Use?

  • 17 March 2023
If you are starting to build a new application or you are working on an existing one you may be wondering whether you should be building a…
Hexagonal Architecture: What Is It and Why Do You Need It?

Hexagonal Architecture: What Is It and Why Do You Need It?

  • 17 February 2023
We all do our best to try and write clean code that is going to be easy to maintain in the future. As time goes on and the application gets…
Snake Case vs Camel Case vs Pascal Case vs Kebab Case

Snake Case vs Camel Case vs Pascal Case vs Kebab Case

  • 06 February 2023
Coming up with names for things when writing software is hard. You need to come up with a few words that neatly describe everything you have…
What is CRUD? CRUD Operations in APIs

What is CRUD? CRUD Operations in APIs

  • 01 February 2023
90% of software that you use every day are what we call CRUD applications. Most of the time we are using them without even realising it…
Why Developers Should Embrace No-Code Solutions

Why Developers Should Embrace No-Code Solutions

  • 09 January 2023
The best line of code is the one you didn’t have to write. As developers, we love writing code. At the end of the day, it is what we are…