API Documentation

Authentication

Our API uses token-based authentication. To access protected resources, you need to include an API key or an OAuth 2.0 bearer token in the Authorization header of your requests.

GET /auth/token

Obtain an authentication token.

Parameters

Name Type Required Description
grant_type String Yes Must be client_credentials for client-side authentication.
client_id String Yes Your application's client ID.
client_secret String Yes Your application's client secret.

Success Response (200 OK)

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Example Request

cURL
JavaScript
curl -X POST \
  https://api.yourdomain.com/auth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'
fetch('https://api.yourdomain.com/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    'grant_type': 'client_credentials',
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET'
  })
})
.then(response => response.json())
.then(data => console.log(data));

All requests to protected endpoints must include the following header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Endpoints

GET /users

Retrieve a list of all users.

Query Parameters

Name Type Required Description
limit Integer No Maximum number of users to return. Default is 20.
offset Integer No Number of users to skip. Default is 0.

Success Response (200 OK)

[
  {
    "id": "user_abc123",
    "name": "Alice Wonderland",
    "email": "alice@example.com",
    "created_at": "2023-10-27T10:00:00Z"
  },
  {
    "id": "user_def456",
    "name": "Bob The Builder",
    "email": "bob@example.com",
    "created_at": "2023-10-27T10:05:00Z"
  }
]
POST /users

Create a new user.

Request Body (JSON)

{
  "name": "Charlie Chaplin",
  "email": "charlie@example.com",
  "password": "securepassword123"
}

Success Response (201 Created)

{
  "id": "user_ghi789",
  "name": "Charlie Chaplin",
  "email": "charlie@example.com",
  "created_at": "2023-10-27T10:10:00Z"
}
GET /users/{id}

Retrieve a specific user by their ID.

Path Parameters

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

Success Response (200 OK)

{
  "id": "user_abc123",
  "name": "Alice Wonderland",
  "email": "alice@example.com",
  "created_at": "2023-10-27T10:00:00Z"
}

Error Response (404 Not Found)

{
  "error": "User not found",
  "message": "The specified user ID does not exist."
}
PUT /users/{id}

Update an existing user's information.

Path Parameters

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

Request Body (JSON)

{
  "name": "Alice W.",
  "email": "alice.w@example.com"
}

Success Response (200 OK)

{
  "id": "user_abc123",
  "name": "Alice W.",
  "email": "alice.w@example.com",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T11:30:00Z"
}
DELETE /users/{id}

Delete a user by their ID.

Path Parameters

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

Success Response (204 No Content)

No response body is returned on successful deletion.

Error Response (404 Not Found)

{
  "error": "User not found",
  "message": "The specified user ID does not exist."
}
GET /products

Retrieve a list of available products.

Query Parameters

Name Type Required Description
category String No Filter products by category.
search String No Search term for product name or description.

Success Response (200 OK)

[
  {
    "id": "prod_xyz789",
    "name": "Gadget Pro",
    "description": "The latest and greatest gadget.",
    "price": 99.99,
    "category": "Electronics"
  },
  {
    "id": "prod_abc111",
    "name": "Stylish T-Shirt",
    "description": "Comfortable cotton t-shirt.",
    "price": 19.99,
    "category": "Apparel"
  }
]

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses are returned in JSON format with an error and message field.

Code Meaning Description
200 OK Success The request was successful.
201 Created Created The resource was successfully created.
204 No Content No Content The request was successful, but there is no content to return.
400 Bad Request Bad Request The request was invalid or malformed. Check the request body or parameters.
401 Unauthorized Unauthorized Authentication failed or the token is missing/invalid.
403 Forbidden Forbidden You do not have permission to access this resource.
404 Not Found Not Found The requested resource could not be found.
429 Too Many Requests Too Many Requests You have exceeded the rate limit.
500 Internal Server Error Internal Server Error An unexpected error occurred on the server.

Rate Limiting

To ensure fair usage and stability, the API enforces rate limits. You are allowed a certain number of requests per minute. If you exceed this limit, you will receive a 429 Too Many Requests response.

The current rate limit is: 100 requests per minute per API key.

You can check your current rate limit status using the following response headers: