Best Practices for a RESTful API

By Alex Hyett on in Software Development

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:


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 post useful?
If you found this post useful and would like to support me, you can do so by buying me a coffee. Donations help keep this blog ad-free.


Dealing with Imposter Syndrome as a Software Developer

Dealing with Imposter Syndrome as a Software Developer

  • 28 May 2021
I have been a professional software developer for over a decade and I have been writing code for over 25 years. However, sometimes I still…
Using for Integration Testing

Using for Integration Testing

  • 21 May 2021
Last week I showed you how you can use Wiremock in a docker container to mock API calls that your application uses. This week is on a…
Mocking API calls using WireMock

Mocking API calls using WireMock

  • 14 May 2021
It is rare in software development that you are building something in complete isolation from everything else. Generally, you are going to…
Using ngrok to test local websites and APIs

Using ngrok to test local websites and APIs

  • 07 May 2021
Often when I am creating a new website, I want to see how it is going to look on an actual device like my phone or tablet. You can use…
Using GitHub Actions to Deploy to S3

Using GitHub Actions to Deploy to S3

  • 26 March 2021
Recently I went through the process of setting up Drone CI on my Raspberry Pi. The plan was to use my Raspberry Pi as a build server for…
Getting Started with AWS Step Functions

Getting Started with AWS Step Functions

  • 12 March 2021
I have recently been looking into AWS Step Functions. For those not familiar with them, Step Functions are Amazon’s way of providing a state…
Useful Docker Commands Worth Saving

Useful Docker Commands Worth Saving

  • 12 February 2021
I use docker every day. All the applications I write at work or at home end up in docker containers. Most of the time though, I am only…
Grafana Monitoring on a Raspberry Pi

Grafana Monitoring on a Raspberry Pi

  • 28 January 2021
As you might have seen from my last few posts I have quite a lot running on my Raspberry Pi. I am currently using a Raspberry Pi 2 B which…

Alex Hyett

Alex Hyett

Software Developer, Entrepreneur, Father, and Husband. Engineering Lead at

Want to get in touch? You can find me here:

Join the Newsletter

Subscribe to get my latest content by email.

    I won't send you spam. Unsubscribe at any time.