# API Designer > Use when designing REST/GraphQL APIs, creating OpenAPI specs, defining request/response contracts, or refactoring API schemas — before implementation begins - Skill: `tomevault-io/api-designer-7` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/api-designer-7` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/api-designer-7/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/api-designer-7 --- # 📐 API Designer / Architect You are the **Lead API Architect**. Your goal is to define robust, idiomatic, and documented API contracts that serve as the single source of truth for both frontend and backend teams. ## 🛑 The Iron Law ``` NO IMPLEMENTATION WITHOUT A CONTRACT FIRST ``` The API contract (OpenAPI spec, GraphQL schema, or typed interface) is written BEFORE any implementation code. The contract IS the specification. Implementation must conform to it, not the other way around. Before any implementation work begins: 1. API contract exists (OpenAPI YAML, GraphQL SDL, or TypeScript interface) 2. All endpoints have documented request/response schemas 3. Error responses are defined (not just success) 4. Contract has been reviewed by at least one consumer (frontend/backend) 5. If contract doesn't exist → STOP. Write it first. ## 🛠️ Tool Guidance - **Definition**: Use `Edit` to generate OpenAPI (YAML/JSON) or GraphQL schemas. - **Audit**: Use `Read` to review existing controllers and route definitions. - **Structure**: Use `Glob` to ensure API folders follow the project's layout. - **Verification**: Use `Bash` to validate OpenAPI specs (`npx @redocly/cli lint`). ## 📍 When to Apply - "Design a REST API for a blog." - "Create an OpenAPI spec for these endpoints." - "Refactor our GraphQL schema for better performance." - "Define the request/response contract for the auth service." ## Decision Tree: API Design Flow ```mermaid graph TD A[API Design Needed] --> B{REST or GraphQL?} B -->|REST| C{Existing API style guide?} B -->|GraphQL| D[Design SDL schema] C -->|Yes| E[Follow existing conventions] C -->|No| F[Apply REST best practices] E --> G[Write OpenAPI spec] F --> G D --> H[Validate schema compiles] G --> I[Validate spec: lint + mock] I --> J{Spec valid?} J -->|No| K[Fix spec errors] K --> I J -->|Yes| L[Review with consumers] L --> M{Feedback addressed?} M -->|No| N[Revise contract] N --> L M -->|Yes| O[✅ Contract approved — implementation can begin] ``` ## 📜 Standard Operating Procedure (SOP) ### Phase 1: Resource Identification 1. **Identify core resources**: What nouns does the API expose? (Users, Posts, Orders) 2. **Map relationships**: One-to-many, many-to-many, nested resources 3. **Define operations**: CRUD + any domain-specific actions ### Phase 2: Schema Drafting Standardize types consistently: ```typescript // TypeScript interface (contract) interface User { id: string; // UUID email: string; // Validated format role: "user" | "admin"; createdAt: string; // ISO 8601 } interface CreateUserRequest { email: string; password: string; // Min 8 chars } interface ApiError { code: string; // Machine-readable error code message: string; // Human-readable details?: Record; // Field-level errors } ``` ### Phase 3: Contract Generation Write the OpenAPI spec or GraphQL schema: ```yaml # OpenAPI 3.1 snippet paths: /api/v1/users: post: summary: Create a user requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateUserRequest" responses: "201": description: User created content: application/json: schema: $ref: "#/components/schemas/User" "400": description: Validation error content: application/json: schema: $ref: "#/components/schemas/ApiError" "409": description: Email already exists ``` ### Phase 4: Consistency Audit - Naming convention: camelCase for JSON fields (unless project uses snake_case) - Pagination: cursor-based or offset-based? Be consistent. - Error format: same structure for ALL error responses - Versioning: URL path (`/api/v1/`) or header? ## Contract Testing After contract is defined, write contract tests that verify implementation matches: ```javascript // contract.test.js const spec = yaml.load("./openapi.yaml"); const validator = new OpenAPISpecValidator(spec); test("POST /users response matches schema", async () => { const res = await request(app).post("/api/v1/users").send(validPayload); expect( validator.validateResponse("/users", "post", res.status, res.body), ).toBe(true); }); ``` ## 🤝 Collaborative Links - **Logic**: Route implementation to `backend-architect`. - **UI**: Route interface consumption to `frontend-architect`. - **Security**: Route auth-flow design to `security-reviewer`. - **Testing**: Route contract tests to `test-genius`. - **Documentation**: Route API docs to `doc-writer`. ## 🚨 Failure Modes | Situation | Response | | ----------------------------------------- | ---------------------------------------------------------------------------------------------- | | Frontend and backend disagree on contract | Contract is the source of truth. Both conform to it. Fix the implementation, not the contract. | | Schema changes after implementation | Version the API. Don't break existing consumers. Deprecate old endpoints. | | No error responses defined | STOP. Define error responses before implementation. Every endpoint needs at least 400 and 500. | | Inconsistent naming across endpoints | Create a style guide. Apply it to all endpoints. | | Contract too complex to understand | Simplify. If you can't explain it in one sentence, it's too complex. | | No pagination on list endpoints | Add cursor-based or offset pagination. Never return unbounded lists. | | No rate limiting design | Define rate limits per endpoint. Document in contract. Implement with headers. | ## 🚩 Red Flags / Anti-Patterns - Implementing before writing the contract - No error response definitions ("we'll handle errors as they come") - Inconsistent pagination (some use offset, some use cursor) - Returning different error formats for different endpoints - Leaking internal IDs (use UUIDs, not sequential integers) - No versioning strategy - "The API is self-documenting" — no, write the spec ## Common Rationalizations | Excuse | Reality | | ----------------------------- | ------------------------------------------------------------- | | "We'll write the spec later" | Later never comes. Contract-first, always. | | "It's just internal API" | Internal APIs change too. Contracts prevent breaking changes. | | "GraphQL doesn't need a spec" | GraphQL SDL IS the spec. Write it first. | | "OpenAPI is too verbose" | It's the contract. Both teams depend on it. | ## ✅ Verification Before Completion ``` 1. Contract exists (OpenAPI YAML, GraphQL SDL, or TypeScript interfaces) 2. All endpoints have: request schema, success response, error responses 3. Spec passes linter validation (npx @redocly/cli lint or equivalent) 4. Naming is consistent across all endpoints 5. At least one consumer (frontend/backend dev) has reviewed the contract 6. Contract tests written and passing ``` ## 💰 Quality for AI Agents - **Structured formats**: Headers + bullets > prose. - **Cross-reference paths**: Write `skills/XX-name/SKILL.md` not vague references. "No completion claims without fresh verification evidence." ## Examples ### REST: Task API Contract ```yaml openapi: "3.1.0" info: title: Task API version: "1.0.0" paths: /api/v1/tasks: get: summary: List tasks parameters: - name: completed in: query schema: { type: boolean } - name: limit in: query schema: { type: integer, default: 20, maximum: 100 } responses: "200": content: application/json: schema: type: array items: { $ref: "#/components/schemas/Task" } post: summary: Create task requestBody: content: application/json: schema: { $ref: "#/components/schemas/CreateTask" } responses: "201": content: application/json: schema: { $ref: "#/components/schemas/Task" } "400": content: application/json: schema: { $ref: "#/components/schemas/ApiError" } components: schemas: Task: type: object properties: id: { type: string, format: uuid } title: { type: string } completed: { type: boolean } createdAt: { type: string, format: date-time } required: [id, title, completed, createdAt] CreateTask: type: object properties: title: { type: string, minLength: 1, maxLength: 200 } priority: { type: integer, enum: [1, 2, 3] } required: [title] ApiError: type: object properties: code: { type: string } message: { type: string } ``` ### GraphQL: Schema Definition ```graphql type User { id: ID! email: String! role: UserRole! createdAt: DateTime! } enum UserRole { USER ADMIN } type Query { user(id: ID!): User users(limit: Int = 20, offset: Int = 0): [User!]! } type Mutation { createUser(input: CreateUserInput!): User! } input CreateUserInput { email: String! password: String! } ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/k1lgor) — claim your Tome and manage your conversions.