API Documentation - Our Awesome Service

Introduction

Welcome to the API documentation for Our Awesome Service. This API allows you to interact with our core functionalities, manage users, retrieve product information, and much more.

We strive to provide a RESTful API with clear endpoints, standard HTTP methods, and consistent JSON responses. Please familiarize yourself with the documentation to make the most of our service.

Authentication

All API requests must be authenticated. We use API Keys for authentication. Your API Key can be found in your account settings.

Include your API Key in theAuthorization header of your requests as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Requests without valid authentication will receive a 401 Unauthorized response.

API Endpoints

GET /users

Retrieves a list of all users.

Query Parameters

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

Responses

200 OK

{
  "data": [
    {
      "id": 1,
      "username": "johndoe",
      "email": "john.doe@example.com",
      "created_at": "2023-10-26T10:00:00Z"
    },
    {
      "id": 2,
      "username": "janedoe",
      "email": "jane.doe@example.com",
      "created_at": "2023-10-26T10:05:00Z"
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}

401 Unauthorized

{
  "error": "Authentication required"
}

POST /users

Creates a new user.

Request Body

The request body must be a JSON object with the following properties:

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 (minimum 8 characters).	Yes

{
  "username": "newuser",
  "email": "new.user@example.com",
  "password": "securepassword123"
}

Responses

201 Created

Returns the newly created user object.

{
  "id": 3,
  "username": "newuser",
  "email": "new.user@example.com",
  "created_at": "2023-10-26T11:30:00Z"
}

400 Bad Request

Returned if the request body is invalid or missing required fields.

{
  "error": "Invalid request body",
  "details": {
    "username": "Username is already taken.",
    "email": "Email is invalid."
  }
}

401 Unauthorized

{
  "error": "Authentication required"
}

GET /users/{id}

Retrieves a specific user by their ID.

Path Parameters

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

Responses

200 OK

{
  "id": 1,
  "username": "johndoe",
  "email": "john.doe@example.com",
  "created_at": "2023-10-26T10:00:00Z"
}

401 Unauthorized

{
  "error": "Authentication required"
}

404 Not Found

Returned if a user with the specified ID does not exist.

{
  "error": "User not found"
}

PUT /users/{id}

Updates an existing user by their ID.

Path Parameters

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

Request Body

The request body can contain any of the user's updatable properties:

Name	Type	Description	Required
username	string	New username.	No
email	string	New email address.	No
password	string	New password.	No

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

Responses

200 OK

Returns the updated user object.

{
  "id": 1,
  "username": "johndoe",
  "email": "john.doe.updated@example.com",
  "created_at": "2023-10-26T10:00:00Z"
}

400 Bad Request

Returned if the request body is invalid.

{
  "error": "Invalid request body",
  "details": {
    "email": "Email format is invalid."
  }
}

401 Unauthorized

{
  "error": "Authentication required"
}

404 Not Found

Returned if a user with the specified ID does not exist.

{
  "error": "User not found"
}

DELETE /users/{id}

Deletes a user by their ID.

Path Parameters

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

Responses

204 No Content

Indicates successful deletion. No response body is returned.

401 Unauthorized

{
  "error": "Authentication required"
}

404 Not Found

Returned if a user with the specified ID does not exist.

{
  "error": "User not found"
}

GET /products

Retrieves a list of available products.

Query Parameters

Name	Type	Description	Required
category	string	Filters products by a specific category.	No
search	string	Search term to find products by name or description.	No

Responses

200 OK

{
  "data": [
    {
      "id": 101,
      "name": "Super Gadget",
      "description": "An amazing gadget that does everything.",
      "price": 199.99,
      "category": "Electronics"
    },
    {
      "id": 102,
      "name": "Mega Widget",
      "description": "A must-have widget for your collection.",
      "price": 49.50,
      "category": "Accessories"
    }
  ],
  "total": 2
}

401 Unauthorized

{
  "error": "Authentication required"
}

POST /products

Creates a new product.

Request Body

The request body must be a JSON object with the following properties:

Name	Type	Description	Required
name	string	The name of the product.	Yes
description	string	A detailed description of the product.	Yes
price	number	The price of the product.	Yes
category	string	The category the product belongs to.	Yes

{
  "name": "Advanced Tool",
  "description": "A sophisticated tool for advanced users.",
  "price": 75.00,
  "category": "Tools"
}

Responses

201 Created

Returns the newly created product object.

{
  "id": 103,
  "name": "Advanced Tool",
  "description": "A sophisticated tool for advanced users.",
  "price": 75.00,
  "category": "Tools",
  "created_at": "2023-10-26T12:00:00Z"
}

400 Bad Request

Returned if the request body is invalid or missing required fields.

{
  "error": "Invalid request body",
  "details": {
    "price": "Price must be a positive number."
  }
}

401 Unauthorized

{
  "error": "Authentication required"
}

Error Handling

Our API uses standard HTTP status codes to indicate the success or failure of a request. Error responses will be in JSON format and include an informative message.

2xx: Success codes.
4xx: Client error codes (e.g., invalid request, unauthorized).
5xx: Server error codes (e.g., internal server error).

A typical error response looks like this:

{
  "error": "A brief description of the error."
}

For some client errors, a details field may be included to provide more specific information about the validation errors.

Rate Limiting

To ensure fair usage and stability, API requests are rate-limited. The current limits are:

1000 requests per hour per API key.

If you exceed the rate limit, you will receive a 429 Too Many Requests response. The response headers will typically include:

X-RateLimit-Limit: The maximum 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 current window resets.

Please implement exponential backoff in your client to handle these responses gracefully.