API Docs

User API

GET /users

Retrieves a list of all registered users.

Request

No request body is required for this endpoint.

Query Parameters

Name Type Description Required
limit integer The maximum number of users to return. Defaults to 20. No
offset integer The number of users to skip before returning results. Defaults to 0. No
sort_by string Field to sort users by (e.g., 'name', 'createdAt'). No
order string Sort order ('asc' or 'desc'). Defaults to 'asc'. No

Response

200 OK

A JSON array containing user objects.


[
  {
    "id": "a1b2c3d4",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "createdAt": "2023-10-27T10:30:00Z",
    "isActive": true
  },
  {
    "id": "e5f6g7h8",
    "username": "janedoe",
    "email": "jane.doe@example.com",
    "createdAt": "2023-10-27T11:00:00Z",
    "isActive": false
  }
]

Error Responses

400 Bad Request

If query parameters are invalid.


{
  "error": "Invalid parameter 'limit'. Must be an integer."
}
500 Internal Server Error

If there's an unexpected server error.

GET /users/{id}

Retrieves a specific user by their unique identifier.

Request

No request body is required for this endpoint.

Path Parameters

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

Response

200 OK

A JSON object representing the user.


{
  "id": "a1b2c3d4",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "createdAt": "2023-10-27T10:30:00Z",
  "isActive": true,
  "roles": ["user", "editor"]
}

Error Responses

404 Not Found

If a user with the specified ID does not exist.


{
  "error": "User not found."
}
400 Bad Request

If the ID format is invalid.

POST /users

Creates a new user account.

Request Body

A JSON object containing the user's details.


{
  "username": "newuser",
  "email": "new.user@example.com",
  "password": "securePassword123!",
  "roles": ["user"]
}

Request Body Parameters

Name Type Description Required
username string The desired username. Must be unique. Yes
email string The user's email address. Must be unique and valid. Yes
password string The user's password. Should meet complexity requirements. Yes
roles array[string] An array of roles to assign to the user (e.g., "user", "admin"). No (defaults to ["user"])

Response

201 Created

The newly created user object, including its assigned ID.


{
  "id": "i9j0k1l2",
  "username": "newuser",
  "email": "new.user@example.com",
  "createdAt": "2023-10-28T09:00:00Z",
  "isActive": true,
  "roles": ["user"]
}

Error Responses

400 Bad Request

If required fields are missing or invalid (e.g., invalid email format, weak password).


{
  "error": "Email is already in use."
}
409 Conflict

If the username or email already exists.


{
  "error": "Username 'newuser' is already taken."
}

PUT /users/{id}

Updates an existing user's information.

Request Body

A JSON object containing the fields to update.


{
  "email": "john.doe.updated@example.com",
  "isActive": false
}

Path Parameters

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

Request Body Parameters

Name Type Description Required
username string The new username. Must be unique if changed. No
email string The new email address. Must be unique and valid if changed. No
isActive boolean Sets the active status of the user. No
roles array[string] An array of roles to assign to the user. Replaces existing roles. No
password string The new password. Should meet complexity requirements. No

Response

200 OK

The updated user object.


{
  "id": "a1b2c3d4",
  "username": "johndoe",
  "email": "john.doe.updated@example.com",
  "createdAt": "2023-10-27T10:30:00Z",
  "isActive": false,
  "roles": ["user"]
}

Error Responses

400 Bad Request

If required fields are missing or invalid (e.g., invalid email format).

404 Not Found

If a user with the specified ID does not exist.

409 Conflict

If the updated username or email already exists.

DELETE /users/{id}

Deletes a user account by their unique identifier.

Request

No request body is required for this endpoint.

Path Parameters

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

Response

204 No Content

Indicates successful deletion with no response body.

Error Responses

404 Not Found

If a user with the specified ID does not exist.

400 Bad Request

If the ID format is invalid.

403 Forbidden

If the authenticated user does not have permission to delete the specified user.