API Reference

Authentication

GET /api/v1/auth/status

Check the current authentication status of the user.

Parameters

Name Type Required Description
token string No Authentication token for verification.

Responses

Status Code Description Schema
200 OK Authentication successful. { authenticated: boolean, user_id: string | null }
401 Unauthorized Invalid or missing authentication token. { error: string }

Example Response (200 OK)

{
    "authenticated": true,
    "user_id": "user-12345"
}

POST /api/v1/auth/login

Log in a user with credentials.

Parameters

Name Type Required Description
username string Yes The user's username.
password string Yes The user's password.

Responses

Status Code Description Schema
200 OK Login successful. { token: string, user_id: string }
401 Unauthorized Invalid credentials. { error: string }

Example Response (200 OK)

{
    "token": "eyJhbGciOiJIUzI1NiIsIn...",
    "user_id": "user-12345"
}

Users

GET /api/v1/users/{user_id}

Retrieve details for a specific user.

Parameters

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

Responses

Status Code Description Schema
200 OK User details retrieved successfully. { id: string, username: string, email: string, created_at: string }
404 Not Found User with the specified ID not found. { error: string }

Example Response (200 OK)

{
    "id": "user-12345",
    "username": "john_doe",
    "email": "john.doe@example.com",
    "created_at": "2023-10-27T10:00:00Z"
}

POST /api/v1/users

Create a new user.

Parameters

Name Type Required Description
username string Yes The desired username.
email string Yes The user's email address.
password string Yes The user's password.

Responses

Status Code Description Schema
201 Created User created successfully. { id: string, message: string }
400 Bad Request Invalid input data (e.g., missing fields, invalid email). { error: string }
409 Conflict Username or email already exists. { error: string }

Example Response (201 Created)

{
    "id": "user-67890",
    "message": "User created successfully."
}

Data Operations

GET /api/v1/items

Retrieve a list of items.

Parameters

Name Type Required Description
limit integer No Maximum number of items to return. Defaults to 20.
offset integer No Number of items to skip. Defaults to 0.

Responses

Status Code Description Schema
200 OK List of items retrieved. Array<{ id: string, name: string, value: any }>

Example Response (200 OK)

[
    {
        "id": "item-abc",
        "name": "Sample Item 1",
        "value": 100
    },
    {
        "id": "item-def",
        "name": "Sample Item 2",
        "value": "Some Text"
    }
]

GET /api/v1/items/{item_id}

Retrieve details for a specific item.

Parameters

Name Type Required Description
item_id string Yes The unique identifier of the item.

Responses

Status Code Description Schema
200 OK Item details retrieved successfully. { id: string, name: string, value: any, created_at: string }
404 Not Found Item with the specified ID not found. { error: string }

Example Response (200 OK)

{
    "id": "item-abc",
    "name": "Sample Item 1",
    "value": 100,
    "created_at": "2023-10-27T11:30:00Z"
}

PUT /api/v1/items/{item_id}

Update an existing item.

Parameters

Name Type Required Description
item_id string Yes The unique identifier of the item to update.
name string No The new name for the item.
value any No The new value for the item.

Responses

Status Code Description Schema
200 OK Item updated successfully. { id: string, message: string }
400 Bad Request Invalid input data. { error: string }
404 Not Found Item with the specified ID not found. { error: string }

Example Response (200 OK)

{
    "id": "item-abc",
    "message": "Item updated successfully."
}

DELETE /api/v1/items/{item_id}

Delete a specific item.

Parameters

Name Type Required Description
item_id string Yes The unique identifier of the item to delete.

Responses

Status Code Description Schema
204 No Content Item deleted successfully. N/A
404 Not Found Item with the specified ID not found. { error: string }