HTTP Status Code & Typical Usage

HttpStatusCode.md

HTTP Status Code & Typical Usage

This page will be used to note down different commonly used status code and the scenarios.

Http Status Code: 200 OK

200 OK, which means it succeeded.

Typically used as a response for synchronous operations.

Use with GET

For example, to fetch the resource:

sequenceDiagram
    Frontend->>+Backend: HTTP GET /
    Note right of Backend: Fetch the resource
    Backend->>-Frontend: 200 OK
    Note over Frontend,Backend: Data fetched successfully

Loading

It is commonly used with other verbs too.

Use with HEAD

For example, with HEAD, returns an empty body but everything else in the headers. It is useful to check if a heavy resource exists or not.

sequenceDiagram
    Frontend->>+Backend: HTTP HEAD /
    Note right of Backend: Check if the resource exists
    Backend->>-Frontend: 200 OK
    Note over Frontend,Backend: It does exist

Loading

Use with POST

Work with POST to return the representation of the resource in the body that has just been created:

sequenceDiagram
    Frontend->>+Backend: HTTP POST /
    Note right of Backend: Item sychroniously created
    Backend->>-Frontend: 200 OK
    Note over Frontend,Backend: item returned in body

Loading

Http Status Code: 201 Created

This status code is typically employed with the HTTP POST method to synchronously create new items.

sequenceDiagram
    Frontend->>+Backend: POST /movies
    Note right of Backend: Creates a movie
    Backend->>-Frontend: 201 Created

Loading

Additional Information

• The response may not directly contain the created movie object; instead, it often provides a URL reference.
• This URL reference sometimes can be found either in the response header or within the response body.

Example Response Header

Location: https://www.hostname.com/movies/new-movie-id

Example Response Body:

{
    "item": "https://www.hostname.com/movies/new-movie-id"
}

It also doesn't have to be json.

Http Status Code: 202 Accepted

In 202, I find your request acceptable, but I may choose to process it or not. Regardless, you can gather additional information from the location specified in the response header.

Considering a movie processing scenario:

sequenceDiagram
    participant U as Browser
    participant A as API
    participant P as Movie processing Queue
    participant S as Status
    participant R as Resource
    participant M as Movie Processor
    
    M-->>P: Listening
    U->>+A: POST /movies
    Note right of A: Try to process a movie
    A->>P: Enqueue MSG
    P-->>A: OK
    P->>+M: Dequeue MSG
    M->>M: Processing
    A->>-U: 202 Accepted
    Note right of U: Get location header
    loop when not ready
        U->>+S: GET /movies-jobs/{new-movie-id}
        S->>-U: 200 OK (status-InProgress)
    end
    M->>-R: Write the Movie
    U->>+S: GET /movie-jobs/{new-movie-id}
    S->>-U: 302 Redirect (status-Ready)
    U->>+R: GET /movies/{new-movie-id}
    R->>-U: 200 OK

Loading

More to come...