61ea975c79
Adds the full bedroom-developer-docs OpenSpec change implementation: - docs/developers/README.md — index page - docs/developers/quick-start.md — bootstrap to working token in 7 steps - docs/developers/concepts.md — AgentIdP, AGNTCY, lifecycle, OAuth 2.0, free tier - docs/developers/guides/README.md — guide index - docs/developers/guides/register-an-agent.md — all fields, validation, common errors - docs/developers/guides/manage-credentials.md — generate, list, rotate, revoke - docs/developers/guides/issue-and-revoke-tokens.md — OAuth 2.0 flow, introspect, revoke - docs/developers/guides/query-audit-logs.md — filters, pagination, 90-day retention - docs/developers/api-reference.md — all 14 endpoints, all error codes, curl examples Also commits deferred OpenSpec housekeeping from previous session: - Archives phase-1-mvp-implementation change to openspec/changes/archive/ - Adds bedroom-developer-docs change artifacts (30/30 tasks complete) - Syncs 4 delta specs to openspec/specs/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
51 lines
3.4 KiB
Markdown
51 lines
3.4 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: API reference exists at docs/developers/api-reference.md
|
|
The system SHALL provide a human-readable API reference at `docs/developers/api-reference.md` covering all 14 endpoints across the four services: Agent Registry, OAuth 2.0 Token, Credential Management, and Audit Log.
|
|
|
|
#### Scenario: Developer finds any endpoint within 10 seconds
|
|
- **WHEN** the developer opens the API reference
|
|
- **THEN** they SHALL find a table of contents at the top linking to each of the four service sections
|
|
|
|
### Requirement: Every endpoint is documented with method, path, description, and auth requirements
|
|
For each of the 14 endpoints, the reference SHALL document: HTTP method, path, one-sentence description, and whether Bearer token auth is required.
|
|
|
|
#### Scenario: Developer knows which endpoints require authentication
|
|
- **WHEN** the developer scans the reference
|
|
- **THEN** they SHALL clearly see which endpoints require a Bearer token (all except POST /token) and which do not
|
|
|
|
### Requirement: Every endpoint includes a complete curl example
|
|
For each endpoint, the reference SHALL include at least one complete, runnable curl example with real placeholder values.
|
|
|
|
#### Scenario: Developer copies a curl example and runs it
|
|
- **WHEN** the developer copies a curl example from the reference
|
|
- **THEN** the command SHALL be complete — no ellipses, no `...`, no missing flags — requiring only substitution of their own agentId, token, and base URL
|
|
|
|
### Requirement: Every endpoint documents all request parameters and body fields
|
|
For each endpoint that accepts a request body or query parameters, the reference SHALL list every field with: name, type, required/optional, description, and validation constraints.
|
|
|
|
#### Scenario: Developer knows what fields are required for POST /agents
|
|
- **WHEN** the developer reads the POST /agents section
|
|
- **THEN** they SHALL see a table listing every field, its type, whether it is required, and any constraints (e.g. email format, max length)
|
|
|
|
### Requirement: Every endpoint documents all response codes and response body schemas
|
|
For each endpoint, the reference SHALL document every possible HTTP response code (2xx and 4xx/5xx) with a description and example response body.
|
|
|
|
#### Scenario: Developer understands a 429 response
|
|
- **WHEN** the developer reads the rate limit error documentation
|
|
- **THEN** they SHALL understand what triggered it, what the X-RateLimit-* headers mean, and when they can retry
|
|
|
|
### Requirement: API reference includes a base URL and versioning section
|
|
The reference SHALL include a section at the top explaining the base URL convention, port configuration, and that all endpoints are unversioned in Phase 1.
|
|
|
|
#### Scenario: Developer knows where to send requests
|
|
- **WHEN** the developer reads the base URL section
|
|
- **THEN** they SHALL see the default base URL (http://localhost:3000), how to change the port via environment variable, and a note that versioning will be introduced in Phase 2
|
|
|
|
### Requirement: API reference includes an errors section
|
|
The reference SHALL include a dedicated errors section listing all standard error response shapes, all custom error codes, and their HTTP status code mappings.
|
|
|
|
#### Scenario: Developer handles an AgentNotFoundError
|
|
- **WHEN** the developer reads the errors section
|
|
- **THEN** they SHALL see the exact JSON shape of the error response, the error code string, and the HTTP status (404)
|