Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -511,7 +511,7 @@ arrivalTimeMs := startOfDay.Add(arrivalDuration).UnixMilli()
## New Endpoint Implementation Workflow

### 1. Research and Planning
- Fetch official API documentation from https://developer.onebusaway.org/api/where/methods
- Read the endpoint's page on the [maglev.wiki](https://github.com/OneBusAway/maglev/wiki), including its Implementation Decisions
- Examine production API responses to understand exact JSON structure
- Check existing similar endpoints for patterns and data access methods

Expand Down Expand Up @@ -582,8 +582,12 @@ Maglev supports JSON configuration files with IDE validation via `config.schema.

## REST API Documentation

The official REST API documentation is available at: https://developer.onebusaway.org/api/where/methods
**The [maglev.wiki](https://github.com/OneBusAway/maglev/wiki) spec is the source of truth for endpoint behavior**: request parameters, defaults, response fields and status codes. Each endpoint page describes the Java OneBusAway server's behavior, which Maglev matches unless the page's Implementation Decisions section records a deliberate difference.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some endpoints have no wiki page yet (block, report-problem-with-trip/stop, problem-reports-for-trip/stop), and neither will a new one. Could this add a fallback, e.g. "If the endpoint has no wiki page, follow the Java implementation and flag it in the PR"? Otherwise an agent may fall back to treating openapi.yml as the authority.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok so I added a fallback if an endpoint has no wiki page, follow the Java implementation, not openapi.yml, and flag it in the PR.


The Open API specification is located at https://github.com/OneBusAway/sdk-config/blob/main/stainless/openapi.yml
If an endpoint has no wiki page yet (for example `block` or the report-problem endpoints), follow the Java implementation, not openapi.yml, and flag it in the PR description.

**All API endpoints MUST behave identically to what is defined in this OpenAPI spec.** This is the single source of truth for request parameters, response schemas, field names, types, and status codes. Always fetch the latest version of this spec before implementing new endpoints or modifying existing ones. If the codebase diverges from the spec, the spec wins.
The OpenAPI spec (`testdata/openapi.yml`, synced from [OneBusAway/sdk-config](https://github.com/OneBusAway/sdk-config/blob/main/stainless/openapi.yml)) comes second. It generates the client SDKs and has known errors. For example, it gives trips-for-route's `includeStatus` and `includeSchedule` a default of `false`, where Java and the wiki use `true`.

When the wiki and openapi.yml disagree, follow the wiki and raise the discrepancy on OneBusAway/sdk-config. Don't change Maglev's behavior to match openapi.yml. An endpoint outside the SDK (such as `/api/where/metrics.json`) needs no openapi.yml entry, but the PR description must say why.

The legacy API documentation is at https://developer.onebusaway.org/api/where/methods.
Loading