/api-design

What it is

REST conventions, GraphQL schema patterns, OpenAPI specification, API versioning, and RFC 7807 error standards.

Called by

• /gaia-dev-story (when implementing API endpoints)
• /gaia-review-api
• All stack dev agents

What it does

Defines REST conventions: plural nouns, lowercase with hyphens, max 3 nesting levels, correct HTTP methods and status codes.

Provides GraphQL schema patterns and OpenAPI specification guidance.

Documents API versioning strategies (URL path, header, query parameter).

Specifies RFC 7807 error response format for consistent error handling.

When you will see it surface

• When API endpoints are created during /gaia-dev-story, these conventions guide the implementation.
• API review findings in /gaia-review-api reference these standards.

Technical notes

• Use parameterized queries -- never concatenate user input.
• Status codes must match their semantic meaning (201 for creation, 204 for deletion, etc.).