# API Plan

An API is a contract between components. Create one only when a real boundary needs it. Static, local, or single-process projects may document internal interfaces or file schemas instead.

[Kit README](README.md) · [Project Overview](Project%20Overview.md) · [PRD](Full%20PRD%20Template.md) · [Master Build Prompt](Master%20Build%20Prompt.md) · [Completion Checklist](Project%20Completion%20Checklist.md)

## Candidate Interfaces

| Endpoint or Interface | Purpose | Access | Contract | Failure Cases |
| --- | --- | --- | --- | --- |
| POST /auth/session | primary user action | [AUTH/ROLE] | [REQUEST → RESPONSE] | [ERRORS] |
| GET /sync/changes | supporting workflow | [AUTH/ROLE] | [REQUEST → RESPONSE] | [ERRORS] |
| POST /sync/batch | supporting workflow | [AUTH/ROLE] | [REQUEST → RESPONSE] | [ERRORS] |
| PUT /users/me/notifications | supporting workflow | [AUTH/ROLE] | [REQUEST → RESPONSE] | [ERRORS] |

## Endpoint Template

~~~text
Operation: [METHOD] [VERSIONED PATH]
Purpose: [ONE USER OR SYSTEM OUTCOME]
Authentication: [REQUIRED METHOD OR PUBLIC]
Authorization: [ROLE + OBJECT/TENANT RULE]
Request: [PATH/QUERY/HEADER/BODY SCHEMA]
Validation: [LIMITS AND NORMALIZATION]
Success: [STATUS + RESPONSE SCHEMA]
Errors: [STANDARD CODES + RETRYABILITY]
Idempotency: [KEY/RULE FOR WRITES]
Rate limit: [POLICY]
Observability: [METRIC/LOG WITHOUT SECRETS]
~~~

## Contract Rules

- Validate on the trusted side even when the client validates.
- Authorize the specific object after authentication; possession of an ID is not permission.
- Bound page size, upload size, query complexity, time range, and batch count.
- Use consistent machine-readable errors with a stable code, readable message, field details when safe, and request identifier.
- Make retried creation or side-effect operations idempotent where duplicates matter.
- Do not expose internal stack traces, provider payloads, secrets, or another user’s existence.

## Versioning and Compatibility

Prefer additive changes. Document which fields are optional, default behavior, deprecation dates, and how clients discover changes. A breaking change requires a migration guide, overlap period where feasible, client test, and rollback strategy.

## Testing Matrix

- [ ] Valid request returns the documented status and schema.
- [ ] Missing, malformed, oversized, and unexpected fields are handled consistently.
- [ ] Unauthenticated, unauthorized, wrong-tenant, and object-not-found cases do not leak protected information.
- [ ] Pagination, sorting, filtering, and boundary values are deterministic.
- [ ] Duplicate/retried writes follow the idempotency rule.
- [ ] Dependency timeout and partial failure return safe documented behavior.
- [ ] Documentation examples pass as automated contract tests.

## Decision

For every candidate interface, record **Keep**, **Internal only**, or **Remove**. A mobile project should not expose PUT /users/me/notifications unless a real client and permission model require it.