RESTful API Documentation Markdown Specification Template
markdown
13 hours ago
·
98 lines
·
6 views
API Specification — Service Name
Base URL: https://api.example.com/v1
Authentication
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer <API_TOKEN>
Endpoints
1. List Resources
GET /resources
Returns a paginated list of resources.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Results per page (default: 20, max: 100) |
cursor |
string | No | Opaque pagination cursor |
status |
string | No | Filter by status: active, archived |
Example Request
curl -X GET "https://api.example.com/v1/resources?limit=10" \
-H "Authorization: Bearer <API_TOKEN>" \
-H "Accept: application/json"
Response 200 OK
{
"object": "list",
"data": [
{
"id": "res_8f8e9a2b",
"name": "Production Database Cluster",
"status": "active",
"created_at": 1728432000
}
],
"has_more": false,
"next_cursor": null
}
2. Create Resource
POST /resources
Request Body (application/json)
{
"name": "Redis Secondary Cache",
"environment": "production",
"tags": ["cache", "infra"]
}
Response 201 Created
{
"id": "res_9a3c1b4d",
"name": "Redis Secondary Cache",
"status": "pending_provision",
"created_at": 1728435600
}
Error Handling
Standard HTTP error codes are returned:
| Code | Status | Description |
|---|---|---|
400 |
Bad Request | Validation failure or malformed JSON |
401 |
Unauthorized | Missing or expired Bearer token |
403 |
Forbidden | Insufficient permissions for resource |
404 |
Not Found | Resource does not exist |
429 |
Too Many Requests | Rate limit exceeded (100 req/min) |
500 |
Internal Error | Upstream service failure |
1# API Specification — Service Name
3Base URL: `https://api.example.com/v1`
5## Authentication
7All API requests require a Bearer token in the `Authorization` header:
9```bash
10Authorization: Bearer <API_TOKEN>
11```
13---
15## Endpoints
17### 1. List Resources
19`GET /resources`
21Returns a paginated list of resources.
23#### Query Parameters
25| Parameter | Type | Required | Description |
26|---|---|---|---|
27| `limit` | integer | No | Results per page (default: 20, max: 100) |
28| `cursor` | string | No | Opaque pagination cursor |
29| `status` | string | No | Filter by status: `active`, `archived` |
31#### Example Request
33```bash
34curl -X GET "https://api.example.com/v1/resources?limit=10" \
35 -H "Authorization: Bearer <API_TOKEN>" \
36 -H "Accept: application/json"
37```
39#### Response `200 OK`
41```json
42{
43 "object": "list",
44 "data": [
45 {
46 "id": "res_8f8e9a2b",
47 "name": "Production Database Cluster",
48 "status": "active",
49 "created_at": 1728432000
50 }
51 ],
52 "has_more": false,
53 "next_cursor": null
54}
55```
57---
59### 2. Create Resource
61`POST /resources`
63#### Request Body (`application/json`)
65```json
66{
67 "name": "Redis Secondary Cache",
68 "environment": "production",
69 "tags": ["cache", "infra"]
70}
71```
73#### Response `201 Created`
75```json
76{
77 "id": "res_9a3c1b4d",
78 "name": "Redis Secondary Cache",
79 "status": "pending_provision",
80 "created_at": 1728435600
81}
82```
84---
86## Error Handling
88Standard HTTP error codes are returned:
90| Code | Status | Description |
91|---|---|---|
92| `400` | Bad Request | Validation failure or malformed JSON |
93| `401` | Unauthorized | Missing or expired Bearer token |
94| `403` | Forbidden | Insufficient permissions for resource |
95| `404` | Not Found | Resource does not exist |
96| `429` | Too Many Requests | Rate limit exceeded (100 req/min) |
97| `500` | Internal Error | Upstream service failure |
Replies 0
No replies yet
Every reply is a note. Start a discussion, ask a question, or attach a code snippet.
Notification