Best Practices for a RESTful API

Published | 3 min read

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 web site 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, know 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 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.

ALSO ON ALEXHYETT.COM

Stack vs Heap Memory - What are the differences?

Stack vs Heap Memory - What are the differences?

  • 30 November 2022
In modern programming languages such as C# or Java, we tend to take memory management for granted. Gone are the days when we need to call malloc to request enough memory for our variables. Luckily a lot of that is done for us by the runtimes so we do...
Code Katas: Can They Make You A Better Developer?

Code Katas: Can They Make You A Better Developer?

  • 21 November 2022
They say “practice makes perfect”, although I much prefer “practice makes improvement”. Either way, how do you practice being a programmer? If you are already working as a software developer then you will be getting some practice from working on larg...
Git Flow vs GitHub Flow

Git Flow vs GitHub Flow

  • 10 November 2022
Losing code that you have spent hours writing can be painful, which is why we use version control (or source control) to store our code and manage changes. Version control is even more important if you are working in a team, without it code, changes ...
I Posted on YouTube Consistently for 1 Month. This is What Happened!

I Posted on YouTube Consistently for 1 Month. This is What Happened!

  • 02 November 2022
As part of my creative sabbatical, I have been posting a new software development video on my YouTube channel every Monday and Friday. It takes a long time to grow on YouTube, and I knew this going in but I have been pleasantly surprised with my grow...
Bitwise Operators and WHY we use them

Bitwise Operators and WHY we use them

  • 26 October 2022
Bitwise operators are one of those concepts that a lot of programmers don’t understand. These are not used a great deal anymore so you can get away with not knowing them but they can still come in handy for a number of different scenarios. If you end...
8 Data Structures you NEED to Know

8 Data Structures you NEED to Know

  • 26 October 2022
You can get pretty far in programming without understanding Data Structures, but eventually, you are going to need to know them, understand how they work and when to use them. https://www.youtube.com/watch?v=SCkbQSPH--A What is a data structure? A da...
Binary Numbers Explained for Programmers

Binary Numbers Explained for Programmers

  • 21 October 2022
Everyone knows that computers run on ones and zeros. This is because CPUs are made up of billions of transistors, which are basically just on-off switches. Any code you write needs to be processed by a computer and therefore has to be converted to b...
Beginners Guide to Programming

Beginners Guide to Programming

  • 12 October 2022
A lot of my articles are aimed at intermediate to advanced developers, but as part of my creative sabbatical, I am working on creating content for those just starting out. So in this post I will be covering some of the many questions that beginner pr...