Thiết kế kỹ thuậtĐộ khó: intermediate
API Contract Designer
Design clean, consistent REST or GraphQL API contracts with versioning strategy, error handling, and OpenAPI/schema output.
Dùng được với:ClaudeCodex (GPT-5)OpenAI ChatGPTDeepseek
Khi nào dùng
Use when designing a new API, versioning an existing one, or establishing API standards for a team. Provide resource names and operations.
Ví dụ sử dụng
"Design a REST API for [domain]. Resources: [list]. Apply API Contract Designer."
Select Model
<skill name="API Contract Designer">
<purpose>
# API Contract Designer Skill
## Objective
Design an API contract that is intuitive for consumers, easy to version, and consistent across resources.
## Design Checklist
### 1. Resource Modelling
- Use nouns for resources, verbs for actions: `/orders` not `/getOrders`
- Nested resources max 2 levels: `/orders/{id}/items` ✓; `/users/{id}/orders/{id}/items/{id}/reviews` ✗
- Plural for collections, singular for singletons
### 2. HTTP Semantics
| Method | Use case | Idempotent | Safe |
|--------|----------|-----------|------|
| GET | Read | ✓ | ✓ |
| POST | Create / non-idempotent action | ✗ | ✗ |
| PUT | Full replace | ✓ | ✗ |
| PATCH | Partial update | ✓* | ✗ |
| DELETE | Remove | ✓ | ✗ |
### 3. Response Conventions
- Always return `{ data, meta, errors }` envelope
- Use HTTP status codes correctly (201 Created, 204 No Content, 422 Unprocessable)
- Error response: `{ code, message, field?, docs_url }`
- Pagination: cursor-based for large/real-time data; offset for small static datasets
### 4. Versioning Strategy
- URL versioning (`/v1/`) for major breaking changes
- Header versioning (`Accept: application/vnd.api+json;version=2`) for minor variants
- Deprecation: 6-month notice, `Deprecation` + `Sunset` response headers
### 5. Security
- AuthN: Bearer token (JWT) in Authorization header — never in URL
- Rate limiting: return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
- Sensitive fields: never in GET params (they appear in logs)
## Output Format
1. Resource list with CRUD matrix
2. OpenAPI 3.1 YAML skeleton for each endpoint
3. Error code registry
4. Versioning decision + migration guide
</purpose>
</skill>