API Specification Template
Template ini digunakan untuk mendokumentasikan API endpoints secara detail dan konsisten.
📋 API Overview
Base URL: https://api.example.com/v1
Authentication: Bearer Token (JWT)
Content-Type: application/json
Rate Limit: 1000 requests/hour per user
🔐 Authentication
Get Access Token
POST /auth/login
Content-Type: application/json
{
"email": "[email protected]",
"password": "password123"
}
Using Token
GET /api/v1/resource
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
📚 Endpoints
1. List Resources
Endpoint: GET /api/v1/resources
Description: Retrieve a paginated list of resources
Authentication: Required
Rate Limit: 100 requests/minute
Request
GET /api/v1/resources?page=1&limit=20&status=active&sort=-createdAt
Authorization: Bearer <token>
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
page | integer | No | 1 | Page number (min: 1) |
limit | integer | No | 20 | Items per page (min: 1, max: 100) |
status | string | No | - | Filter by status: active, inactive, archived |
search | string | No | - | Search by name or description |
sort | string | No | -createdAt | Sort field. Prefix with - for descending |
startDate | string | No | - | Filter by start date (ISO 8601) |
endDate | string | No | - | Filter by end date (ISO 8601) |
Response
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Resource Name",
"description": "Resource description",
"status": "active",
"createdAt": "2024-01-01T10:00:00Z",
"updatedAt": "2024-01-01T10:00:00Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
},
"links": {
"first": "/api/v1/resources?page=1&limit=20",
"prev": null,
"next": "/api/v1/resources?page=2&limit=20",
"last": "/api/v1/resources?page=8&limit=20"
}
}
Response Codes
| Code | Description |
|---|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid or missing token |
| 403 | Forbidden - Insufficient permissions |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
2. Get Resource by ID
Endpoint: GET /api/v1/resources/:id
Description: Retrieve a single resource by ID
Authentication: Required
Request
GET /api/v1/resources/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Path Parameters
| Parameter | Type | Required | Description |
|---|
id | string (UUID) | Yes | Resource ID |
Response
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Resource Name",
"description": "Detailed resource description",
"status": "active",
"owner": {
"id": "660e8400-e29b-41d4-a716-446655440000",
"name": "John Doe",
"email": "[email protected]"
},
"tags": ["tag1", "tag2"],
"metadata": {
"key1": "value1",
"key2": "value2"
},
"createdAt": "2024-01-01T10:00:00Z",
"updatedAt": "2024-01-01T10:00:00Z"
}
}
3. Create Resource
Endpoint: POST /api/v1/resources
Description: Create a new resource
Authentication: Required
Idempotency: Supported via Idempotency-Key header
Request
POST /api/v1/resources
Authorization: Bearer <token>
Idempotency-Key: unique-key-123
Content-Type: application/json
{
"name": "New Resource",
"description": "Resource description",
"status": "active",
"tags": ["tag1", "tag2"],
"metadata": {
"key1": "value1"
}
}
| Header | Required | Description |
|---|
Authorization | Yes | Bearer token |
Idempotency-Key | No | Unique key for idempotent requests (max 255 chars) |
Content-Type | Yes | Must be application/json |
Request Body
| Field | Type | Required | Constraints | Description |
|---|
name | string | Yes | 1-255 chars | Resource name |
description | string | No | max 1000 chars | Resource description |
status | string | No | enum: active, inactive | Default: active |
tags | array[string] | No | max 10 items | Resource tags |
metadata | object | No | max 10 keys | Custom metadata |
Response
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "New Resource",
"description": "Resource description",
"status": "active",
"tags": ["tag1", "tag2"],
"metadata": {
"key1": "value1"
},
"createdAt": "2024-01-01T10:00:00Z",
"updatedAt": "2024-01-01T10:00:00Z"
}
}
4. Update Resource
Endpoint: PUT /api/v1/resources/:id
Description: Update an existing resource (full update)
Authentication: Required
PUT /api/v1/resources/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Updated Resource",
"description": "Updated description",
"status": "inactive"
}
5. Partial Update Resource
Endpoint: PATCH /api/v1/resources/:id
Description: Partially update a resource
Authentication: Required
PATCH /api/v1/resources/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/json
{
"status": "inactive"
}
6. Delete Resource
Endpoint: DELETE /api/v1/resources/:id
Description: Delete a resource (soft delete)
Authentication: Required
DELETE /api/v1/resources/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
📊 Error Codes Reference
| Code | HTTP Status | Description |
|---|
VALIDATION_ERROR | 400 | Request validation failed |
UNAUTHORIZED | 401 | Invalid or missing authentication |
FORBIDDEN | 403 | Insufficient permissions |
RESOURCE_NOT_FOUND | 404 | Resource not found |
DUPLICATE_RESOURCE | 409 | Resource already exists |
RATE_LIMIT_EXCEEDED | 429 | Too many requests |
INTERNAL_ERROR | 500 | Internal server error |
🔄 Webhooks
Webhook Events
POST https://your-webhook-url.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=...
{
"event": "resource.created",
"timestamp": "2024-01-01T10:00:00Z",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "New Resource",
"status": "active"
}
}
Event Types
resource.created - Resource createdresource.updated - Resource updatedresource.deleted - Resource deletedresource.status_changed - Status changed
📚 SDK Examples
package main
import (
"github.com/your/sdk-go"
)
func main() {
client := sdk.NewClient("your-api-key")
// List resources
resources, err := client.Resources.List(&sdk.ListOptions{
Page: 1,
Limit: 20,
})
// Create resource
resource, err := client.Resources.Create(&sdk.Resource{
Name: "New Resource",
Description: "Description",
})
}
import 'package:your_sdk/your_sdk.dart';
void main() async {
final client = YourSDK('your-api-key');
// List resources
final resources = await client.resources.list(
page: 1,
limit: 20,
);
// Create resource
final resource = await client.resources.create(
name: 'New Resource',
description: 'Description',
);
}
Template Usage: Copy section yang relevan untuk dokumentasi API Anda. Sesuaikan endpoint, parameter, dan response sesuai kebutuhan.
