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"
}

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password",
    "traceId": "abc123xyz"
  }
}

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>

curl -X GET "https://api.example.com/v1/resources?page=1&limit=20" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.example.com/v1/resources?page=1&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

final response = await dio.get(
  '/resources',
  queryParameters: {
    'page': 1,
    'limit': 20,
    'status': 'active',
  },
  options: Options(
    headers: {'Authorization': 'Bearer $token'},
  ),
);

req, _ := http.NewRequest("GET", "https://api.example.com/v1/resources?page=1&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, err := client.Do(req)

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"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "details": [
      {
        "field": "limit",
        "message": "limit must be between 1 and 100"
      }
    ],
    "traceId": "abc123xyz"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "traceId": "abc123xyz"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "retryAfter": 60,
    "traceId": "abc123xyz"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "traceId": "abc123xyz"
  }
}

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>

curl -X GET "https://api.example.com/v1/resources/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"

const response = await fetch(
  'https://api.example.com/v1/resources/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: { 'Authorization': 'Bearer <token>' }
  }
);

final response = await dio.get(
  '/resources/550e8400-e29b-41d4-a716-446655440000',
  options: Options(
    headers: {'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"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource with ID 550e8400-e29b-41d4-a716-446655440000 not found",
    "traceId": "abc123xyz"
  }
}

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"
  }
}

curl -X POST "https://api.example.com/v1/resources" \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Resource",
    "description": "Resource description",
    "status": "active"
  }'

const response = await fetch('https://api.example.com/v1/resources', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Idempotency-Key': 'unique-key-123',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'New Resource',
    description: 'Resource description',
    status: 'active'
  })
});

final response = await dio.post(
  '/resources',
  data: {
    'name': 'New Resource',
    'description': 'Resource description',
    'status': 'active',
  },
  options: Options(
    headers: {
      'Authorization': 'Bearer $token',
      'Idempotency-Key': 'unique-key-123',
    },
  ),
);

body := map[string]interface{}{
    "name": "New Resource",
    "description": "Resource description",
    "status": "active",
}
jsonBody, _ := json.Marshal(body)

req, _ := http.NewRequest("POST", "https://api.example.com/v1/resources", bytes.NewBuffer(jsonBody))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "unique-key-123")
req.Header.Set("Content-Type", "application/json")

Request Headers

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"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "name",
        "message": "name is required and must be between 1 and 255 characters"
      },
      {
        "field": "status",
        "message": "status must be one of: active, inactive"
      }
    ],
    "traceId": "abc123xyz"
  }
}

{
  "error": {
    "code": "DUPLICATE_RESOURCE",
    "message": "Resource with name 'New Resource' already exists",
    "traceId": "abc123xyz"
  }
}

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"
}

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Resource",
    "description": "Updated description",
    "status": "inactive",
    "updatedAt": "2024-01-01T11:00:00Z"
  }
}

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"
}

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Resource Name",
    "status": "inactive",
    "updatedAt": "2024-01-01T11:00:00Z"
  }
}

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>

// Empty response body

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found",
    "traceId": "abc123xyz"
  }
}

📊 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 created
resource.updated - Resource updated
resource.deleted - Resource deleted
resource.status_changed - Status changed

📚 SDK Examples

Go
Flutter/Dart

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.

API Specifications

Diagrams & Templates

API Specification Template

API Specification Template

📋 API Overview

🔐 Authentication

Get Access Token

Using Token

📚 Endpoints

1. List Resources

Request

Query Parameters

Response

Response Codes

2. Get Resource by ID

Request

Path Parameters

Response

3. Create Resource

Request

Request Headers

Request Body

Response

4. Update Resource

5. Partial Update Resource

6. Delete Resource

📊 Error Codes Reference

🔄 Webhooks

Webhook Events

Event Types

📚 SDK Examples

​API Specification Template

​📋 API Overview

​🔐 Authentication

​Get Access Token

​Using Token

​📚 Endpoints

​1. List Resources

​Request

​Query Parameters

​Response

​Response Codes

​2. Get Resource by ID

​Request

​Path Parameters

​Response

​3. Create Resource

​Request

​Request Headers

​Request Body

​Response

​4. Update Resource

​5. Partial Update Resource

​6. Delete Resource

​📊 Error Codes Reference

​🔄 Webhooks

​Webhook Events

​Event Types

​📚 SDK Examples

API Specification Template

📋 API Overview

🔐 Authentication

Get Access Token

Using Token

📚 Endpoints

1. List Resources

Request

Query Parameters

Response

Response Codes

2. Get Resource by ID

Request

Path Parameters

Response

3. Create Resource

Request

Request Headers

Request Body

Response

4. Update Resource

5. Partial Update Resource

6. Delete Resource

📊 Error Codes Reference

🔄 Webhooks

Webhook Events

Event Types

📚 SDK Examples