API v2 Documentation

Welcome to the documentation for our v2 API. This section outlines the available endpoints, their parameters, and expected responses.

Authentication

All API requests must be authenticated. Please include your API key in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

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

Endpoints

Resource: Users

GET /api/v2/users

Retrieves a list of all users.

Parameters:

Name	Type	Description	Required
`limit`	Integer	Maximum number of users to return.	No
`offset`	Integer	Number of users to skip.	No

Example Response:


{
  "status": "success",
  "data": [
    {"id": 1, "username": "alice", "email": "alice@example.com"},
    {"id": 2, "username": "bob", "email": "bob@example.com"}
  ],
  "count": 2
}

GET /api/v2/users/{userId}

Retrieves a specific user by their ID.

Parameters:

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

Example Response:


{
  "status": "success",
  "data": {"id": 1, "username": "alice", "email": "alice@example.com"}
}

POST /api/v2/users

Creates a new user.

Request Body:

{
  "username": "string",
  "email": "string",
  "password": "string"
}

Example Response:


{
  "status": "success",
  "data": {"id": 3, "username": "charlie", "email": "charlie@example.com"}
}

Resource: Products

GET /api/v2/products

Retrieves a list of available products.

Parameters:

Name	Type	Description	Required
`category`	String	Filters products by a specific category.	No
`sortBy`	String	Sort order (e.g., 'price', 'name').	No

Example Response:


{
  "status": "success",
  "data": [
    {"id": 101, "name": "Wireless Mouse", "price": 25.99, "category": "Electronics"},
    {"id": 102, "name": "Mechanical Keyboard", "price": 79.99, "category": "Electronics"}
  ],
  "count": 2
}

Error Handling

API errors are returned with a status of error and a descriptive message.

Example Error Response (404 Not Found):


{
  "status": "error",
  "message": "Resource not found."
}

Example Error Response (401 Unauthorized):


{
  "status": "error",
  "message": "Invalid or missing API key."
}

Rate Limiting

To ensure fair usage, the API enforces rate limits. Your current rate limit status can be found in the response headers:

X-RateLimit-Limit: The total 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 rate limit window resets.

If you exceed the rate limit, you will receive a 429 Too Many Requests error.

Need to manage your pet rocks? Check out Pet Rock Management.