API Documentation Update

This document provides comprehensive details about our REST API endpoints with examples and use cases.

Introduction

Our API follows RESTful principles and uses JSON for request and response payloads. All endpoints are secured with OAuth 2.0 authentication.

Authentication

To authenticate with the API, you need to obtain an access token by making a POST request to the /auth endpoint. The token should be included in the Authorization header of all subsequent requests.

POST /api/v1/auth
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

Endpoints

GET /api/v1/users

Returns a list of users. The response can be paginated using the page and limit query parameters.

GET /api/v1/users/:id

Returns details for a specific user identified by the id parameter.

POST /api/v1/users

Creates a new user. The request body should contain the user details.

Error Handling

The API returns appropriate HTTP status codes along with error messages in the response body. Common error codes include:

• 400 - Bad Request: The request was malformed or invalid
• 401 - Unauthorized: Authentication failed or token expired
• 403 - Forbidden: The authenticated user doesn't have permission
• 404 - Not Found: The requested resource doesn't exist
• 500 - Internal Server Error: Something went wrong on the server