This document provides comprehensive documentation for the Task Management REST API. It outlines the available endpoints, authentication methods, request/response formats, and error handling, enabling developers to seamlessly integrate with and utilize the API.
The Task Management REST API provides a robust set of functionalities for managing tasks, users, and categories. It allows applications to create, retrieve, update, and delete tasks, assign them to users, categorize them, and track their status. The API follows RESTful principles, using standard HTTP methods and JSON for data interchange.
Key Features:
All API requests should be prefixed with the following base URL:
https://api.yourdomain.com/v1
(Note: Replace yourdomain.com with the actual domain where the API is hosted.)
The Task Management API uses JSON Web Tokens (JWT) for authentication.
To access protected resources, clients must obtain an access token by logging in. This token must then be included in the Authorization header of subsequent requests.
Endpoint: POST /users/login
Request Body:
---
### 5. Rate Limiting
To ensure fair usage and system stability, the API employs rate limiting.
* **Limit:** 100 requests per minute per IP address.
* **Headers:**
* `X-RateLimit-Limit`: The maximum number of requests allowed in the current period.
* `X-RateLimit-Remaining`: The number of requests remaining in the current period.
* `X-RateLimit-Reset`: The UTC timestamp when the current period will end and the rate limit will reset.
If the rate limit is exceeded, a `429 Too Many Requests` status code will be returned, along with a `Retry-After` header indicating how many seconds to wait before making another request.
---
### 6. Pagination, Filtering, and Sorting
Most list endpoints support common query parameters for data manipulation.
#### 6.1. Pagination
* `page`: (Integer, default: 1) The page number to retrieve.
* `limit`: (Integer, default: 10, max: 100) The number of items per page.
**Example:** `GET /tasks?page=2&limit=5`
#### 6.2. Filtering
* `filter[field]`: (String) Filter resources based on a specific field's value.
* **Example:** `GET /tasks?filter[status]=pending`
* **Operators:** Some fields might support operators like `gt`, `lt`, `gte`, `lte`, `contains`.
* **Example:** `GET /tasks?filter[due_date][gt]=2023-01-01`
* **Example:** `GET /tasks?filter[title][contains]=urgent`
#### 6.3. Sorting
* `sort`: (String) Sort results by one or more fields.
* Prefix with `-` for descending order.
* Multiple fields can be separated by commas.
* **Example:** `GET /tasks?sort=due_date,-created_at` (Sort by `due_date` ascending, then `created_at` descending)
---
### 7. Data Formats
All request and response bodies are formatted as **JSON (JavaScript Object Notation)**.
Clients must send a `Content-Type: application/json` header for requests with a body.
---
### 8. API Endpoints
This section details all available API endpoints.
#### 8.1. User Endpoints
##### 8.1.1. Register a New User
* **Endpoint:** `/users/register`
* **Method:** `POST`
* **Description:** Creates a new user account.
* **Authentication:** None
* **Request Headers:**
* `Content-Type: application/json`
* **Request Body Schema:**
| Field | Type | Required | Description |
| :------- | :------- | :------- | :---------------------------------------- |
| `email` | `string` | Yes | User's email address (must be unique) |
| `password`| `string` | Yes | User's password (min 8 chars) |
| `name` | `string` | No | User's full name |
* **Example Request:**
##### 8.3.2. Create a New Category
/categoriesPOST| Field | Type | Required | Description |
| :------- | :------- | :------- | :------------------------------ |
| name | string | Yes | Name of the category (must be unique for the user) |
##### 8.3.3. Update a Category
/categories/{id}PUT / PATCH * id: (String, required) The unique identifier of the category.
| Field | Type | Required | Description |
| :------- | :------- | :------- | :------------------------------ |
| name | string | Yes | New name of the category (for PUT, only name is updatable) |
##### 8.3.4. Delete a Category
/categories/{id}DELETE * id: (String, required) The unique identifier of the category.
category_id to null for associated tasks, or prevent deletion if tasks are linked). Recommendation: Set category_id to null for associated tasks.The API uses URL-based versioning, indicated by /v1 in the base URL.
https://api.yourdomain.com/v1
Future versions will be released under new prefixes (e.g., /v2) to maintain backward compatibility.
To further enhance the API documentation and development experience, consider the following:
* Interactive Documentation: Tools like Swagger UI can render this specification into interactive API documentation, allowing users to try out endpoints directly in their browser.
* Code Generation: Automatic client SDK generation in various programming languages.
* API Testing: Tools like Postman can import the specification to create collections for testing.
requests), JavaScript (using fetch), and Node.js.For any questions, issues, or feedback regarding the Task Management REST API, please contact our support team at [support@yourdomain.com](mailto:support@yourdomain.com) or visit our developer forum at [https://devforum.yourdomain.com](https://devforum.yourdomain.com).