Skip to content
Search

CodingGuidelines:REST

lastmod 2022-03-11created 2021-07-1312 edits

HTTP Methods

Web developers are likely familiar with GET and POST, along with the other HTTP methods, also sometimes called HTTP verbs. These methods define the type of request being made to a REST API.

Common HTTP methods include:

  • GET: retrieve data, the equivalent to a read in CRUD APIs
  • POST: add new data
  • PUT: update existing data
  • PATCH: update a subset of existing data
  • DELETE: remove data

While there are other methods, they are rarely seen in REST APIs. The method itself does not mean much without the target, the resource.

In my case

  • GET: get data. (SQL Select)
  • PATCH: update data that already exists. (SQL Update)
    • Wikipedia note: A patch is a kind of software designed to update a computer program or its supporting data in order to fix or improve it.
  • DELETE: remove data. (SQL Delete)
  • POST: add data (including SQL Insert and Upsert), and when performing some kind of operation(?). Basically, used for anything that is not Get, Patch, or Delete above.

Applying other requests.

  • HEAD: same as GET, except that the "Response Content" is removed if present. - Check the exact usage later.
  • CONNECT: for tunneling only. Used when Answer communicates directly with a Task. - Check the exact usage later.
  • OPTIONS: used by browsers to set up communication. In other words, do not use. - Check the exact usage later.
  • TRACE: for debugging. - Check the exact usage later.

Should I use it?

  • PUT: The method replaces all current representations of the target resource with the request payload. -> Does this mean it replaces it with the request payload?

Resource Names

Resources are sometimes referred to as the nouns that the HTTP verbs act upon. Earlier web services were built around remote procedure calls, which saw APIs as extensions of the code that called them. By contrast, REST resources can be accessed with multiple HTTP methods, which makes them less analogous to a procedure call.

Example

For example, if your API stored animals, a resource name might be "animals." And the path to access that resource might be /api/animals. The resource would then be combined with HTTP methods like so:

  • GET /api/animals: retrieve a list of animals
  • POST /api/animals: add a new animal
  • GET /api/animals/cat: retrieve a single animal by ID
  • PUT /api/animals/cat: update a single animal by ID
  • DELETE /api/animals/cat: delete an animal by ID

In my case

Use the singular when referring to the thing itself, and the plural when referring to a sub-list.

For example, when expressing two items, "the list of assigned port numbers" and "the range of assignable port numbers (a query for the maximum and minimum values)",

  • GET /api/posts - list of assigned port numbers
  • GET /api/posts/99 - information about port number 99
  • GET /api/post/range - range of assignable port numbers

Remove exception conditions in routing

For example, to make /users/{id} and /users/statistics coexist, the following exception handling is needed.

  1. If the /users/statistics URL is found, route it first.
  2. In /users/{id}, {id} must not be statistics.

This adds unnecessary conditions to the server's path-based routing, and such exception handling increases complexity, especially for people new to the code.

How to design a better REST API

  • How to design better APIs
  • Stay consistent: URLs/headers/authentication/status codes..
  • Use the ISO8601 UTC date format
  • Only Public Endpoints are exempt from authentication. Authentication is required for everything else
  • Provide a health check Endpoint
  • API versioning
  • Apply API key authentication
  • Use sensible HTTP status codes and methods
  • Use simple, self-explanatory names for each Endpoint
  • Use standard error responses
  • Return the resource created by POST
  • PATCH instead of PUT
  • Be as specific as possible
  • Use Pagination
  • Make each resource expandable (design it so additional information can be returned by passing query params such as expand)

See also

Favorite site

Reference site

author Zer0 sitemap