API Reference v1

Introduction

This document provides detailed information about the v1 API endpoints for managing users and related resources. All API requests should be made to the base URL: https://api.example.com/v1.

The API is designed to be RESTful, utilizing standard HTTP methods (GET, POST, PUT, DELETE) and returning data in JSON format.

Authentication

All requests to the API must be authenticated using an API key. The API key should be included in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Obtain your API key from your developer dashboard.

Endpoints

GET /users

GET /users

Retrieves a list of all users.

Query Parameters:

limit (optional, integer)
The maximum number of users to return.
offset (optional, integer)
The number of users to skip from the beginning of the list.

Example Request:

curl -X GET "https://api.example.com/v1/users?limit=10&offset=0" \
     -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK):

{
  "data": [
    {
      "id": "user_abc123",
      "username": "john_doe",
      "email": "john.doe@example.com",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z"
    },
    {
      "id": "user_def456",
      "username": "jane_smith",
      "email": "jane.smith@example.com",
      "createdAt": "2023-10-27T10:05:00Z",
      "updatedAt": "2023-10-27T10:05:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 50
  }
}

POST /users

POST /users

Creates a new user.

Request Body:

username (required, string)
The username for the new user. Must be unique.
email (required, string)
The email address for the new user. Must be valid and unique.
password (required, string)
The password for the new user. Minimum 8 characters.

Example Request:

curl -X POST "https://api.example.com/v1/users" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "new_user",
       "email": "new.user@example.com",
       "password": "securepassword123"
     }'

Example Response (201 Created):

{
  "id": "user_ghi789",
  "username": "new_user",
  "email": "new.user@example.com",
  "createdAt": "2023-10-27T11:00:00Z",
  "updatedAt": "2023-10-27T11:00:00Z"
}

GET /users/{id}

GET /users/{id}

Retrieves a specific user by their ID.

Path Parameters:

id (required, string)
The unique identifier of the user.

Example Request:

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

Example Response (200 OK):

{
  "id": "user_abc123",
  "username": "john_doe",
  "email": "john.doe@example.com",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}

PUT /users/{id}

PUT /users/{id}

Updates an existing user by their ID.

Path Parameters:

id (required, string)
The unique identifier of the user.

Request Body:

username (optional, string)
The new username for the user. Must be unique if provided.
email (optional, string)
The new email address for the user. Must be valid and unique if provided.

Note: Password updates are handled via a separate endpoint (not shown in v1).

Example Request:

curl -X PUT "https://api.example.com/v1/users/user_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "john_doe_updated"
     }'

Example Response (200 OK):

{
  "id": "user_abc123",
  "username": "john_doe_updated",
  "email": "john.doe@example.com",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T11:30:00Z"
}

DELETE /users/{id}

DELETE /users/{id}

Deletes a user by their ID.

Path Parameters:

id (required, string)
The unique identifier of the user.

Example Request:

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

Example Response (204 No Content):

A successful deletion returns no content.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response body will contain a JSON object with an error message:

Common Error Codes:

  • 400 Bad Request: The request was malformed or invalid.
  • 401 Unauthorized: Authentication credentials were missing or invalid.
  • 403 Forbidden: The authenticated user does not have permission to perform the action.
  • 404 Not Found: The requested resource could not be found.
  • 409 Conflict: The request could not be completed due to a conflict (e.g., duplicate username).
  • 500 Internal Server Error: An unexpected error occurred on the server.

Example Error Response (400 Bad Request):

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Username cannot be empty."
  }
}

Versioning

This API is versioned using the URL path (e.g., /v1/). New versions will be introduced to provide backward-incompatible changes. Consumers are encouraged to use specific versions in their requests.

Future versions may be found at paths like /v2/.