Your API Name
Version 1.0 | Base URL: https://api.yourapp.com/v1
Introduction
Welcome to the Your API Name documentation. This API allows you to manage users, posts, and comments. All requests and responses use JSON format.
Base URL:
Protocol: HTTPS only
Format: JSON
https://api.yourapp.com/v1Protocol: HTTPS only
Format: JSON
Authentication
All API requests require authentication using a Bearer token in the Authorization header.
Obtaining an Access Token
POST
/auth/login
Request body:
{
"email": "user@example.com",
"password": "yourpassword"
}
Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
Using the Access Token
Include the token in the Authorization header of all API requests:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Rate Limiting
The API enforces rate limits to ensure fair usage:
- Authenticated requests: 1000 requests/hour
- Unauthenticated requests: 60 requests/hour
Rate limit status is returned in response headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
Users
GET /users
Retrieve a list of all users.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | No | Page number (default: 1) |
limit |
integer | No | Items per page (default: 20, max: 100) |
Example Response
{
"data": [
{
"id": 1,
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:00:00Z"
},
{
"id": 2,
"name": "Jane Smith",
"email": "jane@example.com",
"created_at": "2024-01-16T14:30:00Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 100
}
}
GET /users/{id}
Retrieve a specific user by ID.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer | REQUIRED | User ID |
Example Response
{
"id": 1,
"name": "John Doe",
"email": "john@example.com",
"avatar": "https://example.com/avatar.jpg",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-20T15:30:00Z"
}
POST /users
Create a new user.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | REQUIRED | User's full name |
email |
string | REQUIRED | User's email address |
password |
string | REQUIRED | Password (min 8 characters) |
Example Request
{
"name": "Alice Johnson",
"email": "alice@example.com",
"password": "securepassword123"
}
PUT /users/{id}
Update an existing user.
DELETE /users/{id}
Delete a user.
Response
{
"message": "User deleted successfully"
}
Error Codes
The API uses conventional HTTP response codes:
| Code | Meaning | Description |
|---|---|---|
200 |
OK | Request succeeded |
201 |
Created | Resource created successfully |
400 |
Bad Request | Invalid request parameters |
401 |
Unauthorized | Invalid or missing authentication token |
403 |
Forbidden | Insufficient permissions |
404 |
Not Found | Resource not found |
429 |
Too Many Requests | Rate limit exceeded |
500 |
Internal Server Error | Server encountered an error |
Error Response Format
{
"error": {
"code": 404,
"message": "User not found",
"details": "No user exists with ID 9999"
}
}