In this post, we will learn how to design URL for REST API and what are the best practices to design a URL to a resource. Finally, we will see a case studies of real-world examples.

In the previous post, we learned How to Identify REST Resources. Now it's time to assign URL to the identified resource.

Let's discuss in depth with examples and case studies.

Basically, URL is assigned to the extracted resource for identifying it. It is recommended to use the following formats for the URL.

http(s)://{Domain name (:Port number)}/{A value indicating REST API}/{API version}/{path for identifying a resource}

http(s)://{Domain name indicating REST API(:Port number)}/{API version}/{path for identifying a resource}

Typical examples are:

http://example.com/api/v1/members/M000000001
http://api.example.com/v1/members/M000000001

Let's discuss each part of URL in depth.

Assigning a URL that indicates the API as REST API

It is recommended to include API within the URL domain or path, to clearly indicate that the URL is intended for RESTful Web Service (REST API).
Typically, the URL looks like this:

http://example.com/api/...
http://api.example.com/...

Assigning a URL for identifying the API version

It is recommended to include a value that identifies the API version, in the URL to be published to the client, since it may be necessary to run RESTful Web Service in multiple versions.

Typically, the URL format with version looks like this:

http://example.com/api/{API version}/{path for identifying a resource}
http://api.example.com/{API version}/{path for identifying a resource}

Assigning a path for identifying resource

Let's discuss how to assign a path to a resource with examples. Example: It is the URL used for batch operations of resources

URL format : /{Noun that represents collection of resources}
E.g : /api/v1/members

Example: It is the URL used while operating a specific resource.

URL format: /{Noun that represents collection of resources/resource identifier (ID etc)}
E.g : /api/v1/members/M0001

Example: It is the URL used at the time of batch operation of related resources.

UTI format : {Resource URL}/{Noun representing collection of related resources}
E.g : /api/v1/members/M0001/orders

Example: It is the URL used when operating a specific related resource.

URLFormat: {Resource URL}/{Noun representing collection of related resources}/{Identifier for related resource (ID etc.)}
E.g : /api/v1/members/M0001/orders/O0001

Case Study 1

Let's understand the designing URL for REST API with a real-world example. Let’s write few APIs for Companies which has some Employees, to understand more. /getAllEmployees is an API which will respond with the list of employees. Few more APIs around a Company will look like as follows:

/addNewEmployee

/updateEmployee

/deleteEmployee

/deleteAllEmployees

/promoteEmployee

/promoteAllEmployees

And there will be tons of other API endpoints like these for different operations. All of those will contain many redundant actions. Hence, all these API endpoints would be burdensome to maintain, when API count increases.

What is wrong?

The URL should only contain resources(nouns) not actions or verbs. The API path /addNewEmployee contains the action addNew along with the resource name Employee.

What is the correct way?

/companies endpoint is a good example, which contains no action. But the question is how do we tell the server about the actions to be performed on companies to resource viz. whether to add, delete or update?

This is where the HTTP methods (GET, POST, DELETE, PUT), also called verbs, play the role.

The resource should always be plural in the API endpoint and if we want to access one instance of the resource, we can always pass the id in the URL.

method GET path /companies should get the list of all companies

method GET path /companies/34 should get the detail of company 34

method DELETE path /companies/34 should delete company 34

In a few other use cases, if we have resources under a resource, e.g Employees of a Company, then few of the sample API endpoints would be:

method: GET path: /companies/3/employees should get the list of all employees from company 3

method: GET path: /companies/3/employees/45 should get the details of employee 45, which belongs to company 3

method: DELETE path: /companies/3/employees/45 should delete employee 45, which belongs to company 3

method: POST path: /companies should create a new company and return the details of the new company created

Case Study 2

Let's practice to write URL for different resources extracted from domain information. Consider message and tickets in HelpDesk applications.

If a relation can only exist within another resource, RESTful principles provide useful guidance. These messages can be logically mapped to the /tickets endpoint as follows:

GET /tickets/12/messages - Retrieves a list of messages for ticket #12

GET /tickets/12/messages/5 - Retrieves message #5 for ticket #12

POST /tickets/12/messages - Creates a new message in ticket #12

PUT /tickets/12/messages/5 - Updates message #5 for ticket #12

PATCH /tickets/12/messages/5 - Partially updates message #5 for ticket #12

DELETE /tickets/12/messages/5 - Deletes message #5 for ticket #12

Tips

Resources are nouns, example: /companies

HTTP methods are verbs like GET, POST, PUT, DELETE etc.

Keep resources plural, example : /companies

Case Study 3

Examples from twitter API doc.

Tweets

Curate a collection of Tweets

GET collections/entries

GET collections/list

GET collections/show

POST collections/create

POST collections/destroy

POST collections/entries/add

POST collections/entries/curate

POST collections/entries/move

POST collections/entries/remove

POST collections/update

Look at some widely used APIs to get the hang of this and leverage the intuition of your teammates to refine your API resource URL. Some example APIs are:

Twitter: https://developer.twitter.com/en/docs/api-reference-index

Facebook: http://developers.facebook.com/docs/reference/api/

LinkedIn: https://developer.linkedin.com/apis

Conclusion

In this post, we learned how to design effective URL to identify a unique resource on the internet. IN the next step we will learn How to Assign HTTP methods to REST Resources.