Restful API design

I've never though about correct design of the REST API of my application. My fault. It was time to fix it. Here is a brief summary of the best practices, proposed by Mahesh Haldar, and complement by some of my own researches. The purpose of this post is to have a short summary of REST principles, which can be recalled quickly.

1.  The paths should contain the plural form of resources and the HTTP method should define the kind of action to be performed on the resource.
• The URL should only contain resources(nouns) not actions or verbs
• Http request methods (GET, POST, DELETE, PUT, PATCH) should be used to perform actions:
• GET method requests data from the resource and should not produce any side effect.
• POST method requests the server to create a resource in the database, mostly when a web form is submitted. POST is non-idempotent which means multiple requests will have different effects.
• PUT method requests the server to update resource or create the resource, if it doesn’t exist. PUT is idempotent which means multiple requests will have the same effects.
• DELETE method requests that the resources, or its instance, should be removed from the database.
• PATCH method applies partial modifications to a resource
• 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 
• method GET /companies should get the list of all companies
• method GET /companies/34 should get the detail of company 34
• method DELETE /companies/34 should delete company 34
• If we have resources under a resource:
• GET /companies/3/employees should get the list of all employees from company 3
• GET /companies/3/employees/45 should get the details of employee 45, which belongs to company 3
• DELETE /companies/3/employees/45 should delete employee 45, which belongs to company 3
• POST /companies should create a new company and return the details of the new company created
2. Searching, sorting, filtering, pagination and any other kind of actions which define the way you want the request to be made or result to be returned (in other words, which has no relation to the resources and actions on it)  are done with the query parameters with the GET method API
• Sorting In case, the client wants to get the sorted list of companies, the GET /companies endpoint should accept multiple sort params in the query.
• E.g GET /companies?sort=rank_asc would sort the companies by its rank in ascending order.
• Filtering For filtering the dataset, we can pass various options through query params.
• E.g GET /companies?category=banking&location=india would filter the companies list data with the company category of Banking and where the location is India.
• Searching When searching the company name in companies list the API endpoint should be 
• GET /companies?search=Digital Mckinsey
• Pagination When the dataset is too large, we divide the data set into smaller chunks, which helps in improving the performance and is easier to handle the response. 
• Eg. GET /companies?page=23 means get the list of companies on 23rd page.
3. The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.
• So if we want to update update multiple resources with one request: https://stackoverflow.com/questions/32098423/rest-updating-multiple-resources-with-one-request-is-it-standard-or-to-be-
• A simple REST 
• GET: items/{id} - Returns a description of the item with the given id
• PUT: items/{id} - Updates or Creates the item with the given id
• DELETE: items/{id} - Deletes the item with the given id
• Top-resource 
• GET: items?filter - Returns all item ids matching the filter
• POST: items - Creates one or more items as described by the JSON payload
• PATCH: items - Creates or Updates one or more items as described by the JSON payload:

  
  PATCH /items
  
  [ { id: 1, name: 'foo' }, { id: 2, name: 'bar' } ]