Designing RESTful API URLs
Published on 2021-05-14
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.
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
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
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.