Creating a Great RESTful API

REST is a style of software architecture, often used in web. The design of Rails, for instance, is based a lot on REST. The idea behind this architecture is to have very similar interfaces to access all the resources in your system.

Recently I had to create 2 APIs in 3 months so I had to learn all I could in a very short time. I’d like to share some conclusions but giving the fact that to develop an API people usually say you need 10 years of experience take them with caution.

Use versions

People will trust your API so if you change something in the architecture of your application the 3rd party clients shouldn’t be affected by that.

The common approach here is to add a parameter to your URL, something like:

http://myapp.com/api/v1/

Or:

http://myapp.com/api/1/

I personally prefer the first method since is more clear, Google uses that too.

Use proper HTTP methods

GET: To get a resource or resources of one type.
POST: To create a new resource if you don’t know where it’s going to be.
PUT: To update a resource
DELETE: To remove a resource.

Consistent structure of URLs

If you don’t have a very simple system, probably you’ll end up with a lot of URLs so it’s important to respect a pattern, I used this one:

GET http://example.com/api/cars. To get a list of the resources of one type (cars, for example).
GET http://example.com/api/cars/1. To get a resource with the id 2.
POST http://example.com/api/cars. To create a new resource.
PUT http://example.com/api/cars/1. To update the resource with id 1.
DELETE http://example.com/api/cars/1. To remove the resource with id 1.

Security

I haven’t used the best avaliable method: OAuth. In my case with a token parameter and SSL was enough, but in your case it might not be.

Show examples

There will be a lot of users with a lot of different systems so it would be great if you can provide copy&paste examples. Probably curl will be enough for everyone.

Follow the leaders

Also known as Twitter, Google and Facebook engineers are probably smarter than you. To create my APIs I have ~~copied~~ studied the following APIs: