User API Documentation

Introduction

This document provides detailed information about the User API, allowing you to manage user resources within our platform. You can retrieve, create, update, and delete user data through these endpoints.

All API requests should be made to the base URL: https://api.example.com/v1

The API returns JSON-formatted responses and accepts JSON-formatted request bodies.

Authentication

All requests to the User API require authentication. Please include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

If you do not have an API key, please contact support to obtain one.

API Endpoints

GET /users

Retrieves a list of all users.

Request

No request body is required.

Query Parameters:

Name Type Description Required
limit integer Maximum number of users to return. Default is 20. No
offset integer Number of users to skip. Default is 0. No
sortBy string Field to sort by (e.g., 'createdAt', 'name'). No
sortOrder string 'asc' or 'desc'. Default is 'asc'. No

Response

On success, returns a JSON array of user objects:

[
    {
        "id": "user_123",
        "name": "Alice Smith",
        "email": "alice.smith@example.com",
        "createdAt": "2023-10-27T10:00:00Z",
        "updatedAt": "2023-10-27T10:00:00Z"
    },
    {
        "id": "user_456",
        "name": "Bob Johnson",
        "email": "bob.johnson@example.com",
        "createdAt": "2023-10-27T10:05:00Z",
        "updatedAt": "2023-10-27T10:05:00Z"
    }
]

Example Request

curl -X GET "https://api.example.com/v1/users?limit=10&sortBy=createdAt&sortOrder=desc" -H "Authorization: Bearer YOUR_API_KEY"

GET /users/{id}

Retrieves a specific user by their unique ID.

Request

No request body is required.

Path Parameters:

Name Type Description Required
id string The unique identifier of the user. Yes

Response

On success, returns a JSON object representing the user:

{
    "id": "user_123",
    "name": "Alice Smith",
    "email": "alice.smith@example.com",
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z"
}

Example Request

curl -X GET "https://api.example.com/v1/users/user_123" -H "Authorization: Bearer YOUR_API_KEY"

POST /users

Creates a new user.

Request

Requires a JSON request body with user details.

Name Type Description Required
name string The full name of the user. Yes
email string The email address of the user. Must be unique. Yes
password string The user's password. No (will be auto-generated if not provided)

Response

On success, returns the newly created user object with its generated ID:

{
    "id": "user_789",
    "name": "Charlie Brown",
    "email": "charlie.brown@example.com",
    "createdAt": "2023-10-27T11:00:00Z",
    "updatedAt": "2023-10-27T11:00:00Z"
}

Example Request

curl -X POST "https://api.example.com/v1/users" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "name": "Charlie Brown",
    "email": "charlie.brown@example.com"
}'

PUT /users/{id}

Updates an existing user by their unique ID.

Request

Requires the user's ID in the path and a JSON request body with the fields to update.

Path Parameters:

Name Type Description Required
id string The unique identifier of the user to update. Yes

Request Body Parameters:

Name Type Description Required
name string The full name of the user. No
email string The email address of the user. Must be unique if changed. No

Response

On success, returns the updated user object:

{
    "id": "user_123",
    "name": "Alice Wonderland",
    "email": "alice.wonderland@example.com",
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T11:30:00Z"
}

Example Request

curl -X PUT "https://api.example.com/v1/users/user_123" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "name": "Alice Wonderland"
}'

DELETE /users/{id}

Deletes a user by their unique ID.

Request

No request body is required.

Path Parameters:

Name Type Description Required
id string The unique identifier of the user to delete. Yes

Response

On successful deletion, returns a 204 No Content status code.

If the user is not found, returns a 404 Not Found error.

Example Request

curl -X DELETE "https://api.example.com/v1/users/user_123" -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses will be returned in JSON format and include a message describing the error.

Status Code Description
200 OK Request succeeded.
201 Created Resource successfully created.
204 No Content Request succeeded, but there is no content to return (e.g., successful deletion).
400 Bad Request The request was malformed or invalid (e.g., missing required fields, invalid data format).
401 Unauthorized Authentication failed or was not provided.
403 Forbidden The authenticated user does not have permission to perform the requested action.
404 Not Found The requested resource could not be found.
409 Conflict The request could not be completed due to a conflict with the current state of the resource (e.g., email already exists).
500 Internal Server Error An unexpected error occurred on the server.

Example Error Response (400):

{
    "error": {
        "code": "invalid_input",
        "message": "The 'email' field is required."
    }
}

Rate Limiting

To ensure fair usage and stability, the User API is subject to rate limiting. You can make up to 100 requests per minute per API key.

If you exceed the rate limit, you will receive a 429 Too Many Requests error. The response headers will include:

  • X-RateLimit-Limit: The maximum number of requests allowed in the current window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: The time in UTC epoch seconds when the limit will reset.

Please implement appropriate backoff and retry mechanisms in your application.