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.

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 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

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 to identify a company with identifier 1, you could also choose to use or 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.