api-design
/api-design
Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap.
- Author
- andreibesleaga ↗
- Repository
- gabbe ↗
- Licence
- CC-BY-4.0
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
CC-BY-4.0, otwarta.
What it does and when to use it
Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap.
Original author description
Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap.
How it works
- Goal
- Steps
- Constraints
- Output Format
- Security & Guardrails
SKILL.md preview
---
name: api-design
description: "Design REST/GraphQL/OpenAPI contracts before implementation — API-first approach. Use when: API, endpoint, REST, GraphQL, OpenAPI, API contract, API design, HTTP endpoint, grpc, soap."
license: CC-BY-SA-4.0
metadata:
source: "agents/skills/architecture/api-design.skill.md"
tags: "architecture"
core: "true"
context_cost: "medium"
---
# API Design Skill
## Goal
Design and document API contracts before writing implementation code. API-first development ensures consumers (frontend, mobile, third-party) have stable contracts and implementation details don't leak into the interface.
## Steps
1. **Clarify the API requirements**
- Who are the consumers? (frontend SPA, mobile app, third-party, internal service)
- Protocol? (REST, GraphQL, gRPC, AsyncAPI)
- Auth? (JWT, API key, OAuth2, mTLS)
- Rate limiting & Quotas?
2. **Design the resource model**
```yaml
# Identify resources (nouns, not verbs)
Resources:
- /users -> User resource
- /orders -> Order resource
# Operations
GET /users -> list users (pagination required)
POST /users -> create user (idempotency key required)
```
3. **Define request/response schemas**
- Use explicit schemas — no "any" types.
- **Versioning**: URI Versioning (`/v1/...`) or Header Versioning (`Accept: application/vnd.app.v1+json`).
- **Fields**: camelCase for JSON, snake_case for query params (standard choice).
4. **Define error responses (RFC 7807 Problem Details)**
```json
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"status": 403,
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc"
}
```
5. **Write the Spec**
- **REST**: OpenAPI 3.1 (YAML preferred).
- **GraphQL**: Schema Definition Language (SDL).
- **gRPC**: Protocol Buffers (.proto).
6. **Security considerations**
- All endpoints require authentication unless explicitly public.
- **Scopes**: OAuth2 scopes (`read:users`, `write:orders`).
- Sensitive fields (passwords, PII) never in responses.
7. **Pagination and filtering**
- **Cursor-based**: `?cursor=xyz` (Preferred for infinite scroll/data export).
- **Offset-based**: `?page=1` (OK for admin dashboards).
8. **Validate the design**
- Can all use cases from the PRD be satisfied?
- **N+1 Check**: Does the client need to make 100 calls to get a list? (If so, use `expand` or GraphQL).
9. **Store and share**
- Save spec to: `docs/api/`.
- Lint with Spectral.
## Constraints
- **Breaking Changes**: Strictly forbidden without version bump.
- **IDs**: Use UUIDv4 or nanoID (never auto-increment integers externally).
- **Dates**: ISO 8601 UTC always (`2024-01-01T12:00:00Z`).
## Output Format
API Spec file + summary of design decisions.
## Security & Guardrails
### 1. Skill Security (API Design)
- **Implicit "Any" Blocking**: The agent must strictly forbid the use of unstructured types (e.g., `any` in OpenAPI, or `JSON` scalar types in GraphQL) in the API contract. Every payload must be rigidly bounded and typed to allow code generators and WAFs to automatically reject malformed or exceptionally large payloads (JSON bombing).
- **Wildcard Scope Denial**: When defining OAuth2 or JWT scopes for the API, the agent is strictly prohibited from generating "admin" or wildcard (`*`) scopes. It must decompose authorization down to the resource and action level (e.g., `orders:read`, `orders:write`).
### 2. System Integration Security
- **BOLA/IDOR by Design Validation**: The agent must verify that every single endpoint targeting a specific resource ID (e.g., `GET /users/{id}/billing`) includes a documented authorization pre-condition stating that the authenticated caller has explicit ownership or admin rights to `{id}`. Lack of this documented constraint is an architectural flaw.
- **Rate Limit Blueprinting**: The API design cannot be finalized without explicit rate limiting headers and HTTP 429 schemas defined. The agent must attach quota assumptions to the OpenAPI spec, ensuring the infrastructure team knows the expected burst limits to mitigate L7 DDoS attacks.
### 3. LLM & Agent Guardrails
- **Security-by-Obscurity Hallucination**: The LLM might suggest hiding sensitive internal APIs by placing them on non-standard ports or giving them obfuscated URIs (e.g., `/api/v1/_hidden_debug_77`). The agent must reject this. All endpoints, regardless of intended audience, must enforce explicit Authentication and Authorization layers.
- **REST vs. GraphQL Exposure**: If the agent designs a GraphQL API, it must automatically append mandatory security constraints for depth limiting, complexity analysis, and pagination to prevent resource exhaustion attacks. It cannot output a "raw" GraphQL schema without these defensive properties.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · andreibesleaga/gabbe | 100 | CC-BY-4.0 |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Database snapshot: 13.11.2026 · package version d27c4f709887 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100api-designer
Contract-first API design for REST, GraphQL, gRPC. Design, spec, review, version, compat, sdk. Use for API architecture and OpenAPI specs. NOT for MCP servers (mcp-creator) or frontend API calls. - 90api-designer
API architecture design and documentation for RESTful, GraphQL, and gRPC services. Creates OpenAPI specifications, defines versioning strategies, and establishes authentication/authorization patterns. Use when user asks to design API, create endpoints, document REST/GraphQL, or… - 100api-forge
Design REST/GraphQL APIs with OpenAPI 3.1, error handling, pagination, rate limiting, webhooks, and idempotency. Use when user asks to design an API, create endpoints, define REST/GraphQL schema, or generate OpenAPI spec. Do NOT use for database schema design, frontend API… - 90api-contract-design
REST and GraphQL API design patterns, OpenAPI/Swagger specifications, versioning strategies, and authentication patterns. Use when designing APIs, reviewing API contracts, evaluating API technologies, or implementing API endpoints. - 100api-design-ops
API design patterns for REST, gRPC, and GraphQL. Use for: api design, REST, gRPC, GraphQL, protobuf, schema design, api versioning, pagination, rate limiting, error format, OpenAPI, API authentication, JWT, OAuth2, API gateway, webhook, idempotency. - 100design-api
Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract".