api

API — Design & Specification

Activate When

• User invokes /godmode:api
• User says "design an API", "create API spec", "write API docs"
• User says "validate my API", "is this API well-designed?"
• When building a new service or microservice that exposes endpoints
• When /godmode:plan identifies API-related tasks
• When /godmode:review flags API design issues
• User says "add an endpoint", "api endpoint", "add api endpoint"

Workflow

Step 1: Discovery & Context

Understand what the API needs to do before designing anything:

API DISCOVERY:
Project: <name and purpose>
Type: REST | GraphQL | gRPC | Hybrid
Consumers: <who will call this API — frontend, mobile, third-party, internal services>
Scale: <expected request volume — RPS, concurrent users>
Auth model: <API key, OAuth2, JWT, mTLS, none>
Existing APIs: <list any existing endpoints for consistency>
Constraints: <backward compatibility, regulatory, latency SLAs>

If the user hasn't specified, ask: "What kind of API are we designing? Who will consume it?"

Step 2: Resource Modeling

Identify the core resources and their relationships:

RESOURCE MODEL:
  Resource: <Name>
  Description: <what it represents>
  Attributes:
  - id: string (UUID v4)
  - <field>: <type> (<constraints>)
  - <field>: <type> (<constraints>)
  - created_at: datetime (ISO 8601)
  - updated_at: datetime (ISO 8601)
  Relationships:
  - belongs_to: <Resource> (via <foreign_key>)
  - has_many: <Resource>
  ...

Rules:

• Use nouns for resource names, plural for collections
• Every resource has an id, created_at, updated_at
• Define relationships explicitly — no implicit joins
• Field types must map to the target format (JSON Schema for REST, SDL for GraphQL, protobuf for gRPC)

Step 3: Endpoint Design (REST)

For REST APIs, design endpoints following RESTful conventions:

ENDPOINT CATALOG:
| Method | Path | Description |
|--|--|--|
| GET | /api/v1/<resources> | List <resources> (paginated) |
| POST | /api/v1/<resources> | Create a <resource> |
| GET | /api/v1/<resources>/:id | Get a single <resource> |
| PUT | /api/v1/<resources>/:id | Replace a <resource> |
| PATCH | /api/v1/<resources>/:id | Partial update a <resource> |
| DELETE | /api/v1/<resources>/:id | Delete a <resource> |

Nested resources:
| GET | /api/v1/<parents>/:id/<children> | List children of parent |
  ...

For GraphQL: Define Query (single + list with filter/pagination), Mutation (create, update, delete), and typed response objects.