Designing RESTful API URLs

The URLs of a RESTful API are an important aspect of the user interface for developers that are trying to use the API. They should be consistent and logical, conforming to the REST principals as much as possible.

RESTful principles

In the RESTful principles every URL identifies a resource. If an API gives access to companies, this means every company can be identified by an url, for example example.com/api/companies/1.json. Interacting with that URL using different HTTP methods gives the developer varous abilities:

• GET: read info about the resource
• DELETE: remove the resource
• PUT or PATCH: update the resource
• POST: create the resource, although this is generally done through a different URL, so the API can generate the identifier. For example a POST to example.com/api/companies.json.

API versioning

As stated previously, every URL indentifies a resource. This doesn’t mean other information is not allowed. It is very useful to include the api version in the URL as well. For example, instead of using api.example.com/companies/1.json to identify a company with identifier 1, you could also choose to use v1.example.com/companies/1.json or example.com/api/v1/companies/1.json. This can be helpful if you later want to introduce non-backward compatible changes that might break old clients. The new API version will have new URLs for the resources which can be used by clients that conform to the new API specification.