API Request/Response Examples¶

This reference provides sample HTTP request and response logs for common API interactions. The examples below include inline annotations so you understand what each part of the message does.

Basic GET Request¶

Retrieving a user list from the /api/users endpoint.

GET /api/users HTTP/1.1
Host: example.com
Accept: application/json  # client expects JSON back
Authorization: Bearer <token>

Sample Response¶

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

- 200 OK indicates success. - The body contains a JSON array of user records.

POST Request with JSON Body¶

Submitting a new record to /api/items.

POST /api/items HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Widget",
  "price": 9.99
}

Sample Response¶

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/items/42

{
  "id": 42,
  "name": "Widget",
  "price": 9.99,
  "created_at": "2024-05-01T12:34:56Z"
}

- The server returns 201 Created with the resource location header. - The response body echoes the new item including its generated id.

PUT Request to Update Data¶

Updating the price of item 42.

PUT /api/items/42 HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "price": 11.50
}

Sample Response¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Widget",
  "price": 11.50,
  "updated_at": "2024-05-02T09:30:00Z"
}

- A 200 OK response shows the update succeeded. - The server returns the full item after modification.

DELETE Request¶

Removing an item permanently.

DELETE /api/items/42 HTTP/1.1
Host: example.com
Authorization: Bearer <token>

Sample Response¶

HTTP/1.1 204 No Content

- No body is returned when deletion succeeds.

GET with Query Parameters¶

Retrieving a filtered page of items.

GET /api/items?page=2&limit=5&sort=price HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <token>

Sample Response¶

HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 42

{
  "page": 2,
  "limit": 5,
  "items": [ /* truncated list */ ]
}

- page and limit query parameters request pagination. - X-Total-Count header indicates the total number of items across all pages.

Handling Errors¶

Example of a validation failure when creating an item.

POST /api/items HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "",
  "price": -1
}

Error Response¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "ValidationError",
  "message": "Name is required and price must be positive"
}

- The status code 400 Bad Request signals client-side input issues. - The body provides a structured error with a helpful message.

Request/Response Flow Diagram¶

sequenceDiagram
    participant Client
    participant API
    Client->>API: Send HTTP request
    API-->>Client: Return HTTP response

These examples should help clarify the structure of HTTP requests and responses you will encounter when building and testing APIs during the internship.