API Schema Documentation

Introduction

This document outlines the schema and endpoints for our public API. It provides detailed information on available resources, request parameters, and response structures. Please adhere to this schema for seamless integration.

Authentication

All API requests must be authenticated. Use your provided API key, passed in the Authorization header as a Bearer token. Example: Authorization: Bearer YOUR_API_KEY.

Endpoints

GET /resources/docs/api-schema

Retrieves the API schema documentation.

GET /api/v1/users

Retrieves a list of all users. Supports pagination.

Query Parameters

Name Type Description Required Default
page integer The page number for pagination. No 1
limit integer The number of items per page. No 20
role string Filter users by role. No

Responses

Status Code Description Content
200 OK Successfully retrieved users. 

{
  "data": [
    {
      "id": "user-123",
      "username": "alice",
      "email": "alice@example.com",
      "role": "admin",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    {
      "id": "user-456",
      "username": "bob",
      "email": "bob@example.com",
      "role": "user",
      "createdAt": "2023-10-27T10:05:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 100,
    "nextPage": "/api/v1/users?page=2&limit=20",
    "prevPage": null
  }
}
401 Unauthorized Authentication failed. 

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key."
}
500 Internal Server Error An unexpected error occurred. 

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred on the server."
}
POST /api/v1/users

Creates a new user.

Request Body


{
  "username": "charlie",
  "email": "charlie@example.com",
  "password": "securepassword123",
  "role": "user"
}

Responses

Status Code Description Content
201 Created User successfully created. 

{
  "id": "user-789",
  "username": "charlie",
  "email": "charlie@example.com",
  "role": "user",
  "createdAt": "2023-10-27T11:00:00Z"
}
400 Bad Request Invalid request payload. 

{
  "error": "Bad Request",
  "message": "Missing required field: username"
}
409 Conflict User with this email or username already exists. 

{
  "error": "Conflict",
  "message": "User with this email already exists."
}
GET /api/v1/users/{userId}

Retrieves a specific user by their ID.

Path Parameters

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

Responses

Status Code Description Content
200 OK Successfully retrieved the user. 

{
  "id": "user-123",
  "username": "alice",
  "email": "alice@example.com",
  "role": "admin",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:15:00Z"
}
404 Not Found The specified user ID was not found. 

{
  "error": "Not Found",
  "message": "User with ID 'user-999' not found."
}
PUT /api/v1/users/{userId}

Updates an existing user by their ID.

Path Parameters

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

Request Body


{
  "email": "alice.updated@example.com",
  "role": "editor"
}

Responses

Status Code Description Content
200 OK User successfully updated. 

{
  "id": "user-123",
  "username": "alice",
  "email": "alice.updated@example.com",
  "role": "editor",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T11:30:00Z"
}
404 Not Found The specified user ID was not found. 

{
  "error": "Not Found",
  "message": "User with ID 'user-999' not found."
}
DELETE /api/v1/users/{userId}

Deletes a user by their ID.

Path Parameters

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

Responses

Status Code Description Content
204 No Content User successfully deleted.
404 Not Found The specified user ID was not found. 

{
  "error": "Not Found",
  "message": "User with ID 'user-999' not found."
}

Data Types

Common data types used in the API:

Enums

Values that are restricted to a specific set:

The role field can take one of the following values:

admin, user, editor, guest