REST

Overview#

REST stands for Representational State Transfer.

The guiding principles of REST are:

  1. Client–server – By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
  2. Stateless – Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
  3. Cacheable – Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
  4. Uniform interface – By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
  5. Layered system – The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.
  6. Code on demand (optional) – REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.

Source: https://restfulapi.net/

HTTP Methods#

  • POST: Create
  • GET: Read
  • PUT: Update/Replace
  • PATCH: Update/Modify
  • DELETE: Delete

POST vs PUT#

Both POST/PUT can be used to send data to a server to create/update a resource.

The difference between POST and PUT is that PUT requests are idempotent. That is, calling the same PUT request multiple times will always produce the same result. In contrast, calling a POST request repeatedly have side effects of creating the same resource multiple times.

Source: W3 Schools

Common HTTP Responses#

  • 200: OK
  • 301: Moved Permanently
  • 401: Unauthorized
  • 404: Not Found
  • 403: Forbidden
  • 409: Conflict (resource already exists)
  • 500: Internal Server Error

General Categorization of Response Codes#

  • 1xx: Informational Responses
  • 2xx: Success
  • 3xx - Redirection
  • 4xx - Client Errors
  • 5xx - Server Errors

403 vs 401 Response#

There's a problem with 401 Unauthorized, the HTTP status code for authentication errors. And that’s just it: it’s for authentication, not authorization. Receiving a 401 response is the server telling you, “you aren’t authenticated–either not authenticated at all or authenticated incorrectly–but please reauthenticate and try again.” To help you out, it will always include a WWW-Authenticate header that describes how to authenticate.

This is a response generally returned by your web server, not your web application.

It’s also something very temporary; the server is asking you to try again.

So, for authorization I use the 403 Forbidden response. It’s permanent, it’s tied to my application logic, and it’s a more concrete response than a 401.

Receiving a 403 response is the server telling you, “I’m sorry. I know who you are–I believe who you say you are–but you just don’t have permission to access this resource. Maybe if you ask the system administrator nicely, you’ll get permission. But please don’t bother me again until your predicament changes.”

In summary, a 401 Unauthorized response should be used for missing or bad authentication, and a 403 Forbidden response should be used afterwards, when the user is authenticated but isn’t authorized to perform the requested operation on the given resource.

Credits: Daniel Irvine

Source: Stack Overflow

Idempotence#

When making multiple identical requests has the same effect as making a single request, the REST API is known as idempotent.

Naming Conventions#

  • Use nouns to represent resources (e.g. /users)
  • Pluralized resources unless singleton resource (e.g./users, /users/{id}/address)
  • Forward slashes denote hierarchy
  • No trailing slashes at the end
  • Use hypens for readability
  • Do not use underscores
  • Use lowercase letters
  • Do not use file extensions
  • Never use CRUD function names
  • Use query params to filter URI collection (e.g. /users?region=USA)