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

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

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

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 Specifications

Diagrams & Templates

​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