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.