# 8. API Design

## Prinsip

- **RESTful:** Resource-based URL, HTTP method (GET/POST/PUT/PATCH/DELETE).
- **JSON** request & response; Content-Type: `application/json`.
- **API versioning:** Prefix URL `/api/v1/` (v2 nanti tanpa break v1).

## URL & Method

| Method | Penggunaan |
|--------|------------|
| GET | List (dengan filter, pagination) atau detail satu resource |
| POST | Create |
| PUT/PATCH | Update (PATCH partial) |
| DELETE | Soft delete (prefer) atau hard delete untuk non-kritikal |

Contoh:

- `GET /api/v1/outlets` — list outlet
- `GET /api/v1/outlets/{id}` — detail outlet
- `POST /api/v1/orders` — buat order
- `PATCH /api/v1/orders/{id}/status` — update status order

## Response Format (Standar)

**Success (single):**

```json
{
  "data": { ... },
  "message": "Optional message"
}
```

**Success (list):**

```json
{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 100
  }
}
```

**Error (4xx/5xx):**

```json
{
  "message": "Human readable message",
  "errors": {
    "field_name": ["Validation error 1"]
  },
  "code": "OPTIONAL_ERROR_CODE"
}
```

## Pagination

- Query: `?page=1&per_page=15` (default per_page 15, max 100).
- Response: `meta` berisi `current_page`, `per_page`, `total`, `last_page`.

## Filter & Sort

- Filter: query param (e.g. `?outlet_id=1&status=completed`).
- Sort: `?sort=-created_at` (minus = desc) atau `?sort=created_at`.

## Auth

- Web (session): cookie + CSRF.
- API (mobile/SPA): Bearer token (Laravel Sanctum). Header: `Authorization: Bearer {token}`.

## Rate Limit

- Default: 60 request/menit per user/IP; endpoint login lebih ketat (e.g. 5/menit).
