Glossary: ResponseGlossary

A response, in the context of an API, is a message sent by the server back to the client after processing an API request.

Responses contain information about the result of the request, including whether it was successful, any data requested, and details about any errors that occurred. They onsist of the various components listed below:

• Status code: An HTTP response code, which is a three-digit numeric code indicating the result of the request. Common status codes include:
  • 200 OK: The request was successful.
  • 201 Created: A new resource was successfully created.
  • 400 Bad Request: The request was malformed or invalid.
  • 401 Unauthorized: Authentication is required or has failed.
  • 404 Not Found: The requested resource could not be found.
  • 500 Internal Server Error: An error occurred on the server.
• Headers: Metadata included as part of the response that provide additional information. Common headers include:
  • Content-Type: The media type of the response body. One common type is JSON, represented by a content-type value of application/json.
  • Content-Length: The length of the response body in bytes.
  • Set-Cookie: Used to send cookies from the server to the client.
• Body: The main content of the response, often containing the data requested by the client or details about the result of the request. The body is usually formatted in a standard data interchange format such as JSON or XML.

An API Response Example

Consider an example where a client application has made a GET request to retrieve a user's profile.

Here’s what the request might look like:

GET /v2/user/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer [ACCESS_TOKEN_GOES_HERE]

Here’s what the corresponding response might look like:

• Status code: 200 OK
• Headers:
  • Content-Type: application/json
  • Content-Length: 150
• Body:

{
  "id":         "01234",
  "name":       "Jane Doe",
  "email":      "jane.doe@example.com",
  "created_at": "2024-05-25T12:34:56Z"
}