REST APIs

An API, or application programming interface, is a set of definitions and protocols for building and integrating application software. It’s sometimes referred to as a contract between an information provider and an information user—establishing the content required from the consumer (the call) and the content required by the producer (the response).

A REST API (also known as RESTful API) is an application programming interface that conforms to the constraints of REST architecture. REST stands for representational state transfer.

REST is a set of architectural principles, not a protocol or a standard. API developers can implement REST in a variety of ways.

When a request is made via a RESTful API, it transfers a representation of the state of the resource to the requester. This information, or representation, is delivered in one of several formats via HTTP: JSON (Javascript Object Notation), HTML, XLT, or plain text. JSON is the most generally popular because, despite its name, it’s language agnostic, as well as readable by both humans and machines.

REST implies stateless client-server communication, meaning no client information is stored between requests and each request is separate and unconnected.

REST APIs in 100 seconds (and more)

Basic Architecture

Routes and HTTP methods for a certain resource

Example of REST API routes and specific HTTP methods for a "task" resource

Advantages

• Separates User Interface from Application Logic (at least the one that should be private)

• Using the same Application Logic for various Client Apps. For instance a website and a mobile application.

• Computationally more efficient (less stress on the back-end server and on the network). Redundant resources such as UI templates are sent only once.

• Better for horizontally-scaling the application. We can build micro-serviced APIs, working in parallel, without the Client App being influenced. For instance, an API that deals with all user-flows (registration, authentication, authorization, account management) and a different one for retrieving products and orders.

HTTP response codes

HTTP response codes (or status codes) are three-digit numbers returned by a web server in response to an HTTP request made by a client (such as a web browser or a REST API client). These codes indicate the outcome of the request and provide insight into whether the request was successful, encountered errors, or resulted in redirection.

HTTP response codes are grouped into five classes, with each class representing a different type of response. Here's a breakdown:

1xx – Informational Responses

These status codes indicate that the server has received the request and the client can continue to send more information.

• 100 Continue: The initial part of the request has been received, and the client should continue with the request.

• 101 Switching Protocols: The server is switching to the protocol the client requested, such as WebSocket.

• 102 Processing (WebDAV): The server has received the request, but is still processing it.

2xx – Success

These status codes indicate that the request was successfully received, understood, and accepted.

• 200 OK: The request was successful, and the server has returned the requested data.

• 201 Created: The request was successful, and a new resource has been created as a result.

• 202 Accepted: The request has been accepted for processing, but it hasn't been completed yet.

• 204 No Content: The server successfully processed the request, but there is no content to return.

• 206 Partial Content: The server is delivering only part of the resource due to a range header sent by the client.

3xx – Redirection

These status codes indicate that the client must take additional actions to complete the request, often involving redirection to another URL.

• 301 Moved Permanently: The requested resource has been permanently moved to a new URL.

• 302 Found: The requested resource is temporarily located at a different URL.

• 303 See Other: The client should retrieve the resource at another URI using a GET request.

• 304 Not Modified: The resource has not been modified since the last request, so the client can use a cached version.

• 307 Temporary Redirect: Similar to 302, but the method and body should not be changed when following the redirect.

• 308 Permanent Redirect: Similar to 301, but it keeps the original HTTP method (like POST or PUT).

4xx – Client Errors

These status codes indicate that the client made an error in the request.

• 400 Bad Request: The server couldn't understand the request due to invalid syntax.

• 401 Unauthorized: Authentication is required and has failed or hasn't been provided.

• 403 Forbidden: The server understands the request but refuses to authorize it (usually a permissions issue).

• 404 Not Found: The requested resource could not be found on the server.

• 405 Method Not Allowed: The request method (like GET or POST) is not allowed for the requested resource.

• 408 Request Timeout: The server timed out waiting for the request from the client.

• 409 Conflict: The request could not be processed because of a conflict with the current state of the resource.

• 410 Gone: The requested resource is no longer available and has been permanently removed.

• 429 Too Many Requests: The client has sent too many requests in a given amount of time (rate limiting).

5xx – Server Errors

These status codes indicate that the server encountered an error and could not complete the request.

• 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.

• 501 Not Implemented: The server does not support the functionality required to fulfill the request.

• 502 Bad Gateway: The server, while acting as a gateway or proxy, received an invalid response from an upstream server.

• 503 Service Unavailable: The server is not ready to handle the request (due to maintenance or overloading).

• 504 Gateway Timeout: The server, while acting as a gateway or proxy, did not get a response from the upstream server in time.

• 505 HTTP Version Not Supported: The server does not support the HTTP protocol version used in the request.

---

Commonly Used HTTP Response Codes in Practice:

• 200 OK: Everything went fine (often seen in web pages and API requests).

• 404 Not Found: The requested URL or resource does not exist (common for broken links).

• 500 Internal Server Error: Something went wrong on the server's side, and the request couldn't be processed.

• 403 Forbidden: The user does not have the necessary permissions to access the requested resource.

• 401 Unauthorized: Authentication failed or wasn't provided, and access to the resource is denied.

These codes provide essential feedback for users and developers to understand the status of their HTTP requests and troubleshoot issues accordingly.

Extra: common mistaken HTTP codes

Here are some simple examples of common HTTP response codes that are often mistakenly used or misunderstood:

1. Mistaken use of 404 Not Found instead of 410 Gone

Scenario: A blog post was deleted permanently.

• Mistaken Response: 404 Not Found

  Explanation: Many developers return a 404 when a resource (like a blog post) is missing. However, 404 means the resource may never have existed, or it could just be temporarily unavailable.

• Correct Response: 410 Gone

  Explanation: 410 Gone should be used when a resource has been intentionally removed and will not be available again. This tells the client the resource is permanently gone.

---

2. Mistaken use of 403 Forbidden instead of 401 Unauthorized

Scenario: A user tries to access a page that requires login, but they are not logged in.

• Mistaken Response: 403 Forbidden

  Explanation: Developers sometimes return 403 when a user is not authenticated. However, 403 means the server understood the request but refuses to fulfill it, typically due to permissions (even if the user is authenticated).

• Correct Response: 401 Unauthorized

  Explanation: 401 Unauthorized should be returned when authentication is required but has not been provided or has failed (e.g., invalid credentials).

---

3. Mistaken use of 500 Internal Server Error instead of 400 Bad Request

Scenario: A user submits a form with malformed data (e.g., missing required fields or sending invalid JSON).

• Mistaken Response: 500 Internal Server Error

  Explanation: Many developers use 500 as a catch-all for errors, even when the issue is with the client's request, not the server. 500 implies a server-side issue.

• Correct Response: 400 Bad Request

  Explanation: 400 Bad Request should be returned when the server cannot process the request due to client-side errors (e.g., bad syntax, invalid data).

---

4. Mistaken use of 302 Found instead of 307 Temporary Redirect

Scenario: A web page temporarily redirects users to another URL.

• Mistaken Response: 302 Found

  Explanation: Developers sometimes use 302 Found for temporary redirects. However, 302 can cause issues with POST/PUT requests because clients might change the HTTP method to GET when following the redirect.

• Correct Response: 307 Temporary Redirect

  Explanation: 307 should be used because it ensures that the original HTTP method (like POST) is maintained when following the redirect.

---

5. Mistaken use of 204 No Content instead of 200 OK

Scenario: An API request to update a user’s profile is successful, and the server wants to confirm the update.

• Mistaken Response: 204 No Content

  Explanation: Developers sometimes return 204 No Content when the operation is successful but don’t have content to return. However, if the client expects any confirmation, such as a success message, 204 should not be used.

• Correct Response: 200 OK

  Explanation: Use 200 OK when the operation is successful and you need to return some data, such as a confirmation message or updated resource data. If no content is returned, 204 is appropriate, but only when the body is intentionally empty.

---

6. Mistaken use of 405 Method Not Allowed instead of 400 Bad Request

Scenario: A client sends an invalid request method (like PATCH when only POST or GET are supported).

• Mistaken Response: 405 Method Not Allowed

  Explanation: 405 is meant to indicate that the requested method (e.g., POST, GET) is known by the server but disabled or not allowed for that resource.

• Correct Response: 400 Bad Request

  Explanation: If the method isn't allowed because the client sent a malformed request or incorrect HTTP method, then 400 Bad Request is more appropriate.