API Spec - Contoh REST API (Bahasa Indonesia)

Ringkasan
--------
API ini adalah contoh RESTful API yang bisa dipakai untuk manajemen pengguna, item, dan pesanan. Menggunakan JSON untuk request/response. Autentikasi memakai Bearer Token (JWT).

Base URL
--------
- https://api.example.com/v1

Header Umum
-----------
- Authorization: Bearer <token>  (kecuali endpoint login/register)
- Content-Type: application/json
- Accept: application/json

Autentikasi
-----------
- POST /auth/login
  - Body (application/json):
    {
      "email": "user@example.com",
      "password": "string"
    }
  - Response 200:
    {
      "access_token": "<jwt_token>",
      "token_type": "Bearer",
      "expires_in": 3600
    }
  - Kesalahan: 400 (invalid input), 401 (invalid credentials)

- POST /auth/register
  - Body:
    {
      "name": "Nama User",
      "email": "user@example.com",
      "password": "password123"
    }
  - Response 201: user created (id, name, email)

Endpoint Pengguna (Users)
-------------------------
1) GET /users
- Deskripsi: Mendapatkan daftar pengguna (admin)
- Query params:
  - page (int, optional, default=1)
  - per_page (int, optional, default=20, max=100)
  - sort (string, optional, contoh: "created_at:desc")
  - q (string, optional) - pencarian nama/email
- Response 200:
  {
    "data": [ {"id":1, "name":"...", "email":"..."} , ...],
    "meta": {"page":1, "per_page":20, "total":123}
  }

2) GET /users/{id}
- Path params:
  - id (integer, required)
- Response 200: user object
- Errors: 404 jika tidak ditemukan

3) PUT /users/{id}
- Path params: id
- Body (application/json):
  {
    "name": "Nama Baru",
    "email": "email@baru.com"
  }
- Validasi: email harus format valid; name min 2 karakter
- Response 200: updated user

4) DELETE /users/{id}
- Path params: id
- Response 204: no content
- Permissions: hanya admin

Endpoint Item (Items)
---------------------
1) GET /items
- Query params:
  - page, per_page, sort (lihat Users)
  - category (string, optional)
  - min_price, max_price (decimal, optional)
- Response: list items dengan fields id, name, description, price, stock

2) POST /items
- Body:
  {
    "name": "Nama Item",
    "description": "Deskripsi...",
    "price": 125000.50,
    "stock": 10,
    "category": "Elektronik"
  }
- Validasi:
  - name (required, max 255)
  - price (required, >=0)
  - stock (integer, >=0)
- Response 201: created item
- Permissions: admin atau vendor

3) GET /items/{id}
- Response 200: item object
- 404 jika tidak ditemukan

4) PUT /items/{id}
- Body: fields yang boleh diupdate (name, description, price, stock, category)
- Response 200

5) DELETE /items/{id}
- Response 204

Endpoint Pesanan (Orders)
-------------------------
1) POST /orders
- Body:
  {
    "user_id": 12,            // optional jika token sudah mewakili user
    "items": [
      {"item_id": 5, "quantity": 2},
      {"item_id": 7, "quantity": 1}
    ],
    "shipping_address": "Alamat lengkap",
    "note": "Catatan opsional"
  }
- Validasi: setiap item quantity >= 1 dan tersedia di stock
- Response 201:
  {
    "order_id": 987,
    "status": "pending",
    "total": 375000.00
  }

2) GET /orders/{id}
- Path param: id
- Response 200: full order detail (items, prices, shipping, status)
- Permissions: hanya pemilik order atau admin

3) PATCH /orders/{id}/status
- Body: {"status": "shipped"}
- Allowed status: pending, confirmed, shipped, delivered, cancelled
- Permissions: hanya admin atau staff

Format Tanggal dan Numerik
--------------------------
- Tanggal/waktu: ISO 8601 (UTC), contoh: "2024-08-01T12:34:56Z"
- Desimal: titik sebagai pemisah desimal, misal 125000.50

Pagination
----------
- Gunakan page & per_page
- Meta object harus mengandung total, page, per_page, total_pages

Response Error Umum
-------------------
- 400 Bad Request - payload tidak valid
  {
    "error": "invalid_request",
    "message": "Deskripsi kesalahan",
    "details": { "field": ["pesan validasi"] }
  }
- 401 Unauthorized - token tidak ada/invalid/expired
- 403 Forbidden - tidak cukup izin
- 404 Not Found
- 429 Too Many Requests - rate limit
- 500 Internal Server Error

Rate Limiting
-------------
- Contoh: 1000 requests per 1 jam per API key
- Header terkait:
  - X-RateLimit-Limit: 1000
  - X-RateLimit-Remaining: 750
  - X-RateLimit-Reset: 1650000000  (epoch seconds)

Keamanan dan Persyaratan
------------------------
- Semua permintaan harus lewat HTTPS (TLS 1.2+)
- Gunakan header Authorization: Bearer <token>
- CORS: domain yang diijinkan harus didaftarkan
- Validasi input di server (length, tipe, range)
- Sanitasi data untuk mencegah injection

Versioning
----------
- Versi di URL: /v1/
- Buat v2 jika ada breaking change

Contoh Request/Response (cURL)
-----------------------------
Login:
curl -X POST "https://api.example.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

Ambil daftar item:
curl "https://api.example.com/v1/items?page=1&per_page=20" \
  -H "Authorization: Bearer <token>"

Footer
------
Spesifikasi ini adalah contoh umum. Sesuaikan endpoint, nama field, aturan autentikasi, dan kebijakan rate limit sesuai kebutuhan aplikasi Anda.