Immutable. This exact content is served forever at /api/v1/blob/39da8f21331d3a18.
--- name: api-engineering description: >- Expert API design and delivery: resource modeling, versioning, consistent error envelopes, pagination/filtering, idempotency, OpenAPI/contracts, and boundary validation. Use when defining or changing REST (or HTTP) APIs, DTO/request-response shapes, client integration contracts, or when reviewing endpoint consistency before frontend or third-party consumers bind to them. expertise_level: expert --- # API Engineering (Canonical) **Expertise: expert.** Aliases: `api`, `rest-api`, `openapi`, `http-api`. ## When to use - Desain atau ubah endpoint HTTP/REST - Kontrak request/response, status code, error body - Pagination, filtering, sorting, idempotency keys - Spesifikasi OpenAPI / API docs untuk konsumen FE/integrasi ## When not to use - Schema DB murni → `database-engineering` - UI rendering → `frontend-engineering` - Auth protocol detail → `auth-access-control` (koordinasi wajib) ## Procedure 1. **Contract first** — Identifikasi resource, verb, identitas, dan side-effect. 2. **Consistency** — Samakan envelope sukses/error dengan konvensi project. 3. **Boundary** — Validasi input di edge; tolak early; jangan bocorkan detail internal. 4. **Scale reads** — Pagination wajib untuk koleksi; filter eksplisit; urutan deterministic. 5. **Writes** — Idempotency untuk POST yang bisa di-retry; transaksi di service layer. 6. **Authz** — Setiap endpoint sensitif: default deny (lihat `auth-access-control` + `security`). 7. **Document** — Update kontrak/OpenAPI atau docs project; breaking change = version/migrate plan. 8. **Verify** — Smoke happy-path + 4xx validation + 401/403; catat path artifact. Detail: `reference.md`. ## DoD - [ ] Kontrak endpoint jelas (path, method, auth, payload, errors) - [ ] Pagination/filter pada koleksi besar - [ ] Tidak ada breaking change diam-diam - [ ] Validasi + authz di boundary - [ ] Evidence smoke atau blocker eksplisit ## Attribution <!-- ATTRIBUTION: Rogue Development | https://github.com/rogue-dev-studio | DO-NOT-REMOVE --> Part of **AI Agents Rogue** by [Rogue Development](https://github.com/rogue-dev-studio) (`@rogue-dev-studio`). Do not remove, hide, rename, or replace this attribution.