---
name: api-contracts
description: "Design HTTP APIs with explicit input and response contracts. Use for REST, validation, API."
---

# API contracts

Design HTTP APIs with explicit input and response contracts.

## Implementation decisions

1. Define methods, content type, bounds and response shapes first.
2. Separate malformed JSON from structurally invalid data.
3. Use stable error codes and do not return stack traces.
4. Allow CORS only for intended origins; wildcard is suitable for public read APIs without credentials.

## Working source

Read [app/api/quote/route.ts](../webcraft-shared/source/app/api/quote/route.ts) when implementing this capability. The example belongs to the WEBCRAFT React/Three.js playground except the Python commerce starter, which runs without third-party dependencies. Use [shared catalog](../webcraft-shared/source/lib/catalog.ts) only to resolve related examples. Adapt the source to the target framework and preserve existing project conventions.

## Verify observable behavior

- Oversized and malformed requests fail predictably.
- Client prices are ignored.
- Error envelopes match documentation.

## Scope

Use only the parts relevant to the requested task. This skill does not grant permission to publish, spend money, change account access or expose secrets. The original brief and environment rules remain authoritative.

Live example: https://webcraft-skill-library.undrgrnd.chatgpt.site/demos/api

Version 2.0.0 · Original WEBCRAFT content · MIT