20  Spell of API Design

21 Spell of API Design

Working seal: spell://api-design/828C8A1237

Use when: Use when designing a public or durable JSON API surface.

21.1 Copyable Template

Raw template: prompts/spells/api-design.txt

ROLE:
Act as a backend architect designing a public JSON API.

OBJECTIVE:
Design an API for the described resource model that is clean, versionable, secure, and observable.

CONTEXT:
Clients include web, mobile, and internal automation. The system uses OAuth-based authorization and PostgreSQL storage.

Backward compatibility matters because mobile clients update slowly.

CONSTRAINTS:
Prefer boring, maintainable patterns over novelty. Include pagination, error schema, idempotency where appropriate,

authorization notes, and migration considerations. Do not hand-wave failure modes.

PROCEDURE:
Start from the resource model and operations. Then define endpoints, request and response schemas,

error codes, pagination, filtering, authorization checks, and observability requirements.

OUTPUT CONTRACT:
Return:

1\. resource model,

2\. endpoint table,

3\. example requests and responses,

4\. error format,

5\. auth model,

6\. migration and versioning notes.

VERIFICATION:
Call out edge cases, race conditions, and compatibility risks.

FAILURE BEHAVIOR:
If the resource model is underspecified, list the assumptions explicitly before designing.

21.2 Related Runes

• 0055 interface {Arch} - A disciplined seam that lets unlike bodies cooperate without swapping internal organs.
• 0347 schema {Data} - The declared shape of stored meaning.
• 1461 idempotent - The word that makes retries survivable: same request, same lasting effect.
• 0978 authorization - After identity is known, what acts are permitted?
• 1430 backward-compatible - New versions do not casually break old clients or data.

21.3 Related Pages

• Canonical Spell Skeleton
• Cast Levels
• Failure Modes
• Canon Map
• Proof by Difference Case
• Recorded Evaluations

21.4 Source Form

21.5 Spell of API Design

ROLE:

Act as a backend architect designing a public JSON API.

OBJECTIVE:

Design an API for the described resource model that is clean, versionable, secure, and observable.

CONTEXT:

Clients include web, mobile, and internal automation. The system uses OAuth-based authorization and PostgreSQL storage.

Backward compatibility matters because mobile clients update slowly.

CONSTRAINTS:

Prefer boring, maintainable patterns over novelty. Include pagination, error schema, idempotency where appropriate,

authorization notes, and migration considerations. Do not hand-wave failure modes.

PROCEDURE:

Start from the resource model and operations. Then define endpoints, request and response schemas,

error codes, pagination, filtering, authorization checks, and observability requirements.

OUTPUT CONTRACT:

Return:

1. resource model,

2. endpoint table,

3. example requests and responses,

4. error format,

5. auth model,

6. migration and versioning notes.

VERIFICATION:

Call out edge cases, race conditions, and compatibility risks.

FAILURE BEHAVIOR:

If the resource model is underspecified, list the assumptions explicitly before designing.