Responses - Backstack

Handling API responses.

Overview

The API uses a streamlined approach for responses, designed to simplify both session management and data handling. Each response includes essential session headers with JWT authentication, while response bodies follow a consistent format providing success status, user-friendly messages, and structured data. This standardized approach removes complexity from API interactions, allowing developers to focus on building features rather than writing extensive response handling code.

Response headers

The API includes these headers in every response:

HTTP/1.1 200 OK
...
X-Session-Status: current
X-JWT: "eyJ0eXAi..."
content-type: application/json

Use the value provided by the X-Session-Status to manage the current session.

The X-JWT value in includes the following claims:

app_id - The application identifier.
account_id - The account identifier.
user_id - The user identifier.

Response bodies

The response body is designed to easily verify the outcome, display messages, and provide access to the main content. It includes the following properties:

success - A boolean indicating if the request was successful.
message - A string with a user-friendly message suitable for UI feedback.
data - An object containing the requested endpoint data, or an Error object if the request failed.

This ensures a consistent approach in destructuring the response for managing the results of your API requests.

const {success, message, data} = await createUser({...});

console.log(data.name);

if (message) {
    toast(message);
}

Example successful response

{
  "success": true,
  "message": "Cosmos Kramer updated successfully.",
  "data": {
    "id": "usr_1234567890",
    "name": "Cosmos Kramer",
    ...
  }
}

Example error response

{
  "success": false,
  "message": "Required values are missing or invalid.",
  "data": {
    "error": {
      "type": "user",
      "fields": {
        "username": "Required value",
        "password": "Cannot be your username"
      },
      ...
    }
  }
}

Handling responses

Use the response structure to handle the outcome of your API requests.

const {success, message, data} = await updateUser({name: 'Jerry Seinfeld', email: 'jerry@nbc.com'});

if(success) {
    // Do something with the user data ...
}else {
    // Do something with the data.error ...
}

if (message) {
    toast(message);
}