API Design Best Practices: Panduan Lengkap 2026

9. API Documentation

API yang tidak didokumentasikan dengan baik adalah API yang tidak akan digunakan. Berikut best practices untuk API documentation:

Tools API Documentation

Contoh OpenAPI Specification (Snippet)

openapi: 3.0.3
info:
  title: BeebaneLabs API
  version: 1.0.0
  description: API untuk platform tutorial BeebaneLabs

paths:
  /api/v1/articles:
    get:
      summary: Daftar semua artikel
      description: Mengambil daftar artikel dengan pagination
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: category
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Berhasil
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Article'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
    post:
      summary: Buat artikel baru
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleCreate'
      responses:
        '201':
          description: Artikel berhasil dibuat
        '422':
          description: Validasi gagal

Apa yang Harus Ada di API Documentation

1. Getting Started Guide: Quick start, authentication setup, first request
2. Authentication: Cara mendapatkan token, refresh, dan handle error
3. Endpoint Reference: Semua endpoint dengan request/response examples
4. Error Codes: Daftar lengkap error codes dan cara handle
5. Rate Limits: Limitasi dan cara menghandle rate limiting
6. Changelog: Perubahan di setiap versi
7. SDKs & Code Examples: Contoh penggunaan di berbagai bahasa
8. Webhook Documentation: Events, payload format, retry policy

// Integration test dengan Jest + Supertest
const request = require('supertest');
const app = require('../app');

describe('Articles API', () => {
  let authToken;

  beforeAll(async () => {
    // Login untuk mendapatkan token
    const res = await request(app)
      .post('/api/v1/auth/login')
      .send({ email: 'test@example.com', password: 'password123' });
    authToken = res.body.data.access_token;
  });

  describe('GET /api/v1/articles', () => {
    it('should return list of articles', async () => {
      const res = await request(app)
        .get('/api/v1/articles')
        .expect(200);

      expect(res.body.status).toBe('success');
      expect(Array.isArray(res.body.data)).toBe(true);
      expect(res.body.meta).toHaveProperty('page');
      expect(res.body.meta).toHaveProperty('total');
    });

    it('should filter articles by category', async () => {
      const res = await request(app)
        .get('/api/v1/articles?category=javascript')
        .expect(200);

      res.body.data.forEach(article => {
        expect(article.category).toBe('javascript');
      });
    });
  });

  describe('POST /api/v1/articles', () => {
    it('should create new article', async () => {
      const res = await request(app)
        .post('/api/v1/articles')
        .set('Authorization', `Bearer ${authToken}`)
        .send({
          title: 'Test Article',
          content: 'This is test content',
          category: 'testing'
        })
        .expect(201);

      expect(res.body.data).toHaveProperty('id');
      expect(res.body.data.title).toBe('Test Article');
    });

    it('should return 422 for invalid data', async () => {
      const res = await request(app)
        .post('/api/v1/articles')
        .set('Authorization', `Bearer ${authToken}`)
        .send({ title: '' })
        .expect(422);

      expect(res.body.error.code).toBe('VALIDATION_ERROR');
    });

    it('should return 401 without auth token', async () => {
      await request(app)
        .post('/api/v1/articles')
        .send({ title: 'Test' })
        .expect(401);
    });
  });
});

// Rate limit response headers
X-RateLimit-Limit: 100          // Max requests per window
X-RateLimit-Remaining: 75       // Remaining requests
X-RateLimit-Reset: 1687812000   // Unix timestamp when limit resets

// Response 429 Too Many Requests:
{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 30 seconds.",
    "retry_after": 30
  }
}

// Header:
Retry-After: 30