Phase 3 Completed

2026-08-02 17:44:50 +07:00
parent 7ce0de4e91
commit ffc5ecd259
68 changed files with 3132 additions and 163 deletions
@@ -0,0 +1,203 @@
+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.