RESTful API Guidelines — Best Practices

  • Introduction
  • HTTP Request Methods
  • Passing Information in the Request
  • HTTP Response Status Codes
  • Endpoints Naming Guidelines
  • Example Paths, Methods, and Requests
  • Throttling
  • Security
  • Popular Languages and Frameworks
  • Conclusion & Final Thoughts

Introduction

HTTP Request Methods

  • GET → Retrieve a resource or list of resources
  • POST → Create a resource
  • PUT → Update a resource
  • DELETE → Delete a resource

Passing Information in the Request

  • Path parameters → This is passed as part of the path when making a request. Normally used to select a specific resource via its ID.
  • Query parameters →This is what you would see at the end of the path represented by ‘?param1=xx&param2=yy’. Normally used to filter the resources.
  • Headers →These are part of the HTTP Request. They identify the type of content, encoding, among others. You can also add new fields, a common case is ‘x-api-key’ for authorization on a public API.
  • Body →This is used to pass information, normally encoded in JSON, although other formats such as XML can be used. This is where you will pass the information when creating a resource with POST or the fields you will update in a PUT or PATCH request.

HTTP Response Status Codes

  • 200 OK
  • 201 Created
  • 202 Accepted
  • 204 No Content
  • 301 Moved Permanently
  • 304 Not Modified
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable

Endpoints Naming Guidelines

  • Use nouns
  • Use plurals
  • If possible, use a single word — If you need to use multiple words use a hyphen to separate them
  • Use the same route with different HTTP Request types for different actions

Examples:

  • /employing → /employees
  • /house → /houses
  • /create-house →/houses (POST)
  • /update-house/:id →/houses/:id (PUT)

Example Paths, Methods, and Requests

{
"city": string --> Name of the city where it is located
"height": int --> Height of the building in meters
"nStories": int --> Number of stories
"street": string --> Name of the street where it is located
"buildDate": int --> The year when it was built
}
  • POST /buildings → Create a new building
  • GET /buildings → Retrieve the list of all the buildings
  • GET /buildings/:id →Retrieve a building by its id
  • PUT /buildings/:id → Update a building by its id
  • DELETE /buildings/:id → Delete a building by its id

Filters, Sorting, and Pagination

  • filters — We can define a query parameter with the name city to allow the user to filter for buildings in a specific city.
  • pagination — We can also define a page and a limit parameter. The limit would be the number of elements retrieved whilst the page would allow the server to calculate how many elements to skip ahead.
  • sorting — We can use two query parameters: sortBy and sortOrder. The former will select which field we will be sorting by, whilst the latter defines if the order is either ascending or descending.

Examples

  • GET https://www.api.apiexample.com/v1/buildings/1234?page=2&limit=10&city=london
  • POST https://www.api.apiexample.com/v1/buildings/
body:
{
"city": london,
"height": 32,
"nStories": 9,
"street": "5th Avenue",
"buildDate": 1998
}

Throttling

  • Rate-Limit Throttling → Limits the number of requests that can be done in a specific interval of time by a certain user. This implies that you have to authenticate the users.
  • IP-level Throttling →You can limit the number of requests that can be made by each IP Address.

Security

Popular Languages and Frameworks

Conclusion & Final Thoughts

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Miguel Saraiva

Miguel Saraiva

Software Engineer looking to learn & share knowledge.