aiskillstore/marketplace / skills/0xdarkmatter/rest-patterns
rest-patterns
VerifiedQuick reference for RESTful API design patterns, HTTP semantics, caching, and rate limiting. Triggers on: rest api, http methods, status codes, api design, endpoint design, api versioning, rate limiting, caching headers.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
| references/caching-patterns.md | markdown | 3.4 KB |
| references/rate-limiting.md | markdown | 3.6 KB |
| references/response-formats.md | markdown | 4.6 KB |
| references/status-codes.md | markdown | 4.9 KB |
| skill-report.json | config | 34.5 KB |
references/response-formats.md
View on GitHub# Response Formats
Error responses, versioning, bulk operations, and HATEOAS patterns.
## Error Response Format
### Standard Structure
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{"field": "email", "message": "Invalid email format"},
{"field": "age", "message": "Must be 18 or older"}
],
"request_id": "abc-123",
"documentation_url": "https://api.example.com/docs/errors#validation"
}
}
```
### Minimal Error
```json
{
"error": {
"code": "NOT_FOUND",
"message": "User not found"
}
}
```
### Validation Errors (422)
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [
{
"field": "email",
"code": "INVALID_FORMAT",
"message": "Must be a valid email address"
},
{
"field": "password",
"code": "TOO_SHORT",
"message": "Must be at least 8 characters"
}
]
}
}
```
### RFC 7807 Problem Details
```json
{
"type": "https://api.example.com/errors/validation",
"title": "Validation Error",
"status": 422,
"detail": "The request body contains invalid data",
"instance": "/users/123",
"errors": [
{"pointer": "/email", "detail": "Invalid format"}
]
}
```
---
## Versioning Strategies
### URI Versioning (Most Common)
```http
GET /v1/users
GET /v2/users
```
**Pros:** Clear, easy to route, cacheable
**Cons:** URL pollution, hard to deprecate
### Header Versioning
```http
GET /users
Accept: application/vnd.api.v1+json
```
**Pros:** Clean URLs
**Cons:** Harder to test, less visible
### Query Parameter
```http
GET /users?version=1
GET /users?api-version=2024-01-15
```
**Pros:** Easy to implement
**Cons:** Less RESTful, affects caching
### Date-Based Versioning
```http
GET /users
API-Version: 2024-01-15
```
**Pros:** Fine-grained, Stripe-style
**Cons:** Complex to maintain
---
## Bulk Operations
### Batch Endpoint
```http
POST /batch
Content-Type: application/json
{
"operations": [
{"method": "POST", "path": "/users", "body": {"name": "Alice"}},
{"method": "PATCH", "path": "/users/123", "body": {"status": "active"}},
{"method": "DELETE", "path": "/users/456"}
]
}
```
**Response:**
```json
{
"results": [
{"status": 201, "body": {"id": 789, "name": "Alice"}},
{"status": 200, "body": {"id": 123, "status": "active"}},
{"status": 204, "body": null}
]
}
```
### Bulk Create
```http
POST /users/bulk
Content-Type: application/json
[
{"name": "Alice", "email": "alice@example.com"},
{"name": "Bob", "email": "bob@example.com"}
]
```
**Response:**
```json
{
"created": 2,
"items": [
{"id": 123, "name": "Alice"},
{"id": 124, "name": "Bob"}
]
}
```
### Bulk Create with Partial Failure
```json
{
"created": 1,
"failed": 1,
"items": [
{"id": 123, "name": "Alice", "status": "created"}
],
"errors": [
{"index": 1, "error": {"code": "DUPLICATE", "message": "Email exists"}}
]
}
```
### Bulk Delete
```http
DELETE /users/bulk
Content-Type: application/json
{"ids": [1, 2, 3, 4, 5]}
```
**Response:**
```json
{
"deleted": 5
}
```
---
## HATEOAS Links
### Single Resource
```json
{
"id": 123,
"name": "Alice",
"email": "alice@example.com",
"_links": {
"self": {"href": "/users/123"},
"orders": {"href": "/users/123/orders"},
"profile": {"href": "/users/123/profile"},
"update": {"href": "/users/123", "method": "PATCH"},
"delete": {"href": "/users/123", "method": "DELETE"}
}
}
```
### Collection with Pagination
```json
{
"data": [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"}
],
"meta": {
"total": 150,
"page": 2,
"per_page": 20,
"total_pages": 8
},
"_links": {
"self": {"href": "/users?page=2"},
"first": {"href": "/users?page=1"},
"prev": {"href": "/users?page=1"},
"next": {"href": "/users?page=3"},
"last": {"href": "/users?page=8"}
}
}
```
### HAL Format
```json
{
"_embedded": {
"users": [
{"id": 1, "name": "Alice", "_links": {"self": {"href": "/users/1"}}},
{"id": 2, "name": "Bob", "_links": {"self": {"href": "/users/2"}}}
]
},
"_links": {
"self": {"href": "/users?page=1"},
"next": {"href": "/users?page=2"}
},
"page": 1,
"total": 100
}
```
### JSON:API Format
```json
{
"data": [
{
"type": "users",
"id": "1",
"attributes": {"name": "Alice"},
"relationships": {
"orders": {"links": {"related": "/users/1/orders"}}
},
"links": {"self": "/users/1"}
}
],
"links": {
"self": "/users?page=1",
"next": "/users?page=2"
},
"meta": {"total": 100}
}
```
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 |