HK-hub/AgentSkills / api-designer
api-designer
VerifiedUse when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.6 KB |
| references/error-handling.md | markdown | 11.3 KB |
| references/openapi.md | markdown | 16.0 KB |
| references/pagination.md | markdown | 9.4 KB |
| references/rest-patterns.md | markdown | 7.3 KB |
| references/versioning.md | markdown | 7.8 KB |
references/rest-patterns.md
View on GitHub# REST Design Patterns
## Resource-Oriented Architecture
REST APIs are built around resources, not actions. Resources are the nouns of your API.
### Resource Identification
**Good Resource URIs:**
```
GET /users # Collection
GET /users/{id} # Individual resource
GET /users/{id}/orders # Nested collection
POST /users # Create resource
PUT /users/{id} # Replace resource
PATCH /users/{id} # Update resource
DELETE /users/{id} # Delete resource
```
**Bad Resource URIs:**
```
POST /getUser # Verb in URI
POST /createUser # Verb in URI
GET /user?action=delete # Action as query param
```
### Resource Naming Conventions
- Use plural nouns for collections: `/users`, `/orders`, `/products`
- Use lowercase and hyphens for readability: `/shipping-addresses`
- Avoid deep nesting (max 2-3 levels): `/users/{id}/orders/{orderId}`
- Use query parameters for filtering: `/users?status=active&role=admin`
## HTTP Method Semantics
### Safe and Idempotent Methods
| Method | Safe | Idempotent | Use Case |
|--------|------|------------|----------|
| GET | Yes | Yes | Retrieve resource(s) |
| POST | No | No | Create resource, non-idempotent operations |
| PUT | No | Yes | Replace entire resource |
| PATCH | No | No | Partial update |
| DELETE | No | Yes | Remove resource |
| HEAD | Yes | Yes | Get metadata only |
| OPTIONS | Yes | Yes | Get allowed methods |
### Method Usage
**GET - Retrieve Resources**
```http
GET /users/123
Accept: application/json
Response: 200 OK
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
```
**POST - Create Resources**
```http
POST /users
Content-Type: application/json
{
"name": "Jane Smith",
"email": "jane@example.com"
}
Response: 201 Created
Location: /users/124
{
"id": 124,
"name": "Jane Smith",
"email": "jane@example.com",
"created_at": "2024-01-16T14:20:00Z"
}
```
**PUT - Replace Resource**
```http
PUT /users/123
Content-Type: application/json
{
"name": "John Doe Updated",
"email": "john.new@example.com"
}
Response: 200 OK
{
"id": 123,
"name": "John Doe Updated",
"email": "john.new@example.com",
"updated_at": "2024-01-17T09:15:00Z"
}
```
**PATCH - Partial Update**
```http
PATCH /users/123
Content-Type: application/json
{
"email": "john.updated@example.com"
}
Response: 200 OK
{
"id": 123,
"name": "John Doe",
"email": "john.updated@example.com",
"updated_at": "2024-01-17T10:00:00Z"
}
```
**DELETE - Remove Resource**
```http
DELETE /users/123
Response: 204 No Content
```
## HTTP Status Codes
### Success Codes (2xx)
- **200 OK** - Request succeeded (GET, PUT, PATCH)
- **201 Created** - Resource created (POST), include Location header
- **202 Accepted** - Request accepted for async processing
- **204 No Content** - Success with no response body (DELETE)
### Redirection (3xx)
- **301 Moved Permanently** - Resource permanently moved
- **302 Found** - Temporary redirect
- **304 Not Modified** - Cached version is still valid
### Client Errors (4xx)
- **400 Bad Request** - Invalid request syntax or validation error
- **401 Unauthorized** - Authentication required or failed
- **403 Forbidden** - Authenticated but not authorized
- **404 Not Found** - Resource doesn't exist
- **405 Method Not Allowed** - HTTP method not supported for resource
- **409 Conflict** - Request conflicts with current state (e.g., duplicate)
- **422 Unprocessable Entity** - Valid syntax but semantic errors
- **429 Too Many Requests** - Rate limit exceeded
### Server Errors (5xx)
- **500 Internal Server Error** - Unexpected server error
- **502 Bad Gateway** - Invalid response from upstream server
- **503 Service Unavailable** - Server temporarily unavailable
- **504 Gateway Timeout** - Upstream server timeout
## HATEOAS (Hypermedia)
### Hypermedia-Driven APIs
Include links to related resources and available actions:
```json
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"_links": {
"self": { "href": "/users/123" },
"orders": { "href": "/users/123/orders" },
"update": { "href": "/users/123", "method": "PATCH" },
"delete": { "href": "/users/123", "method": "DELETE" }
}
}
```
### HAL (Hypertext Application Language)
```json
{
"id": 123,
"name": "John Doe",
"_links": {
"self": { "href": "/users/123" }
},
"_embedded": {
"orders": [
{
"id": 456,
"total": 99.99,
"_links": {
"self": { "href": "/orders/456" }
}
}
]
}
}
```
## Content Negotiation
### Accept Headers
```http
GET /users/123
Accept: application/json
GET /users/123
Accept: application/xml
GET /users/123
Accept: application/hal+json
```
### Response Content-Type
```http
Content-Type: application/json; charset=utf-8
Content-Type: application/problem+json
Content-Type: application/hal+json
```
## Idempotency
### Idempotent Operations
**PUT - Always idempotent:**
Multiple identical PUT requests produce the same result as a single request.
**DELETE - Idempotent:**
First DELETE returns 204, subsequent DELETEs return 404 (same end state).
**POST - Not idempotent by default:**
Use `Idempotency-Key` header for idempotent POST:
```http
POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"amount": 100.00,
"currency": "USD"
}
```
Server stores idempotency key and returns same response for duplicate requests.
## Cache Control
### Cache Headers
```http
Cache-Control: public, max-age=3600
Cache-Control: private, no-cache
Cache-Control: no-store
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Wed, 15 Jan 2024 10:30:00 GMT
```
### Conditional Requests
```http
GET /users/123
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Response: 304 Not Modified
```
```http
PUT /users/123
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Content-Type: application/json
{
"name": "Updated Name"
}
Response: 412 Precondition Failed (if ETag doesn't match)
```
## URI Patterns
### Consistent URI Structure
```
/{version}/{resource}
/{version}/{resource}/{id}
/{version}/{resource}/{id}/{sub-resource}
/{version}/{resource}/{id}/{sub-resource}/{sub-id}
```
### Query Parameters
**Filtering:**
```
GET /users?status=active&role=admin
GET /products?category=electronics&price_min=100&price_max=500
```
**Sorting:**
```
GET /users?sort=created_at
GET /users?sort=-created_at # Descending
GET /users?sort=name,created_at # Multiple fields
```
**Field Selection:**
```
GET /users?fields=id,name,email
GET /users?exclude=password,social_security_number
```
**Search:**
```
GET /users?q=john
GET /products?search=laptop
```
## Best Practices
1. **Use nouns, not verbs** - Resources are nouns, methods are verbs
2. **Plural collections** - Use `/users` not `/user`
3. **Consistent naming** - Choose snake_case or camelCase and stick to it
4. **Proper status codes** - Use appropriate HTTP status codes
5. **Include metadata** - Pagination, filtering, sorting info in responses
6. **Version your API** - Plan for evolution from day one
7. **Document everything** - OpenAPI specs, examples, error codes
8. **Security by default** - HTTPS, authentication, rate limiting
9. **Support filtering** - Enable clients to get exactly what they need
10. **Implement HATEOAS** - Make APIs self-documenting and discoverable
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |