Architecture

Responses

Handling API responses.


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);
}

Previous
Requests