Repository navigation
Name the wiki spec as the API source of truth - #1844
Ahmedhossamdev merged 4 commits into
Conversation
CLAUDE.md said every endpoint must behave identically to openapi.yml and that the spec wins. The maglev.wiki spec is authoritative in practice, and openapi.yml has known errors: it says trips-for-route's includeStatus and includeSchedule default to false, where Java and the wiki say true. Following the old rule led to PRs that were rejected for that reason. Make the wiki the source of truth, rank openapi.yml second, and say that disagreements go to OneBusAway/sdk-config. Mention endpoints outside the SDK, matching the PR template. Point the new-endpoint workflow at the wiki instead of the legacy API docs.
|
Caution Review failedThe pull request is closed. No actionable comments were generated in the recent review.
|
| Layer / File(s) | Summary |
|---|---|
Research workflow and API source guidance CLAUDE.md |
The research instructions point developers to endpoint wiki pages and Implementation Decisions. The REST API guidance makes the wiki authoritative, treats OpenAPI as secondary, directs discrepancies to OneBusAway/sdk-config, and allows endpoints outside the SDK without an OpenAPI entry when the PR description explains why. The legacy API documentation remains as a reference. |
Estimated code review effort: 1 (Trivial) | ~5 minutes
Change: Other · Severity of issue fixed: Medium
Possibly related issues
OneBusAway/maglev#1710— The issue concerns documenting endpoint behavior and Java differences in the wiki; this change makes the wiki the source of truth.OneBusAway/maglev#1727— The issue concerns missing endpoint wiki pages and Implementation Decisions; this change directs contributors to those pages and decisions.OneBusAway/maglev#1825— The issue concerns wiki and OpenAPI disagreements and the sdk-config update path; this change defines that source precedence and discrepancy workflow.OneBusAway/maglev#1499— The issue concerns Java-versus-Maglev parameter behavior and documenting deviations in Implementation Decisions; this change refers contributors to those decisions.
Possibly related PRs
- OneBusAway/maglev#1755 — It adds endpoint specification documents and maps them to wiki pages, which this change uses for endpoint research and behavior guidance.
Suggested reviewers: aaronbrethorst
Merge Risk: 
Minimal · previous review 345d2
-
No actionable merge-blocking issue was found.
Pre-merge checks: 
5
-
Check name Status Explanation Title check The title clearly and concisely identifies the main change: making the wiki specification the API source of truth. Description check The description follows the repository template, explains the change and root cause, reports testing, and completes the checklist. The response comparison section is not needed because this is a docum… Linked Issues check Issue #1692has no coding requirements. It asks only for documentation changes in CLAUDE.md, and the diff changes only CLAUDE.md. The diff (merge base 138ddad to head 345d22c, CLAUDE.md only) meets ea…Out of Scope Changes check The diff has two hunks, both in CLAUDE.md. The first hunk changes step 1 of the New Endpoint Implementation Workflow to point at the wiki page instead of the legacy API docs. The second hunk rewrites … Docstring Coverage No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0… Full details: Description check
-
Explanation
The description follows the repository template, explains the change and root cause, reports testing, and completes the checklist. The response comparison section is not needed because this is a documentation-only change.
Full details: Linked Issues check
-
Explanation
Issue
#1692has no coding requirements. It asks only for documentation changes in CLAUDE.md, and the diff changes only CLAUDE.md. The diff (merge base 138ddad to head 345d22c, CLAUDE.md only) meets each requested change:- Wiki as source of truth: the REST API Documentation section names the maglev.wiki spec as authoritative for endpoint behavior. It states that Maglev matches Java unless the page's Implementation Decisions section records a difference.
- openapi.yml second: the section ranks testdata/openapi.yml second and gives the trips-for-route includeStatus/includeSchedule example.
- Disagreements raised upstream: the text says to follow the wiki, raise the discrepancy on OneBusAway/sdk-config, and not change Maglev to match openapi.yml.
- Maglev-only endpoints: the text says endpoints outside the SDK (such as /api/ondemand) need no openapi.yml entry if the PR description explains why.
The openapi.yml default values cited in the text were not re-verified in this review. The file read was truncated before the cited lines. This does not affect the verdict, because the claim is explanatory text and the issue states the same defaults.
Full details: Out of Scope Changes check
-
Explanation
The diff has two hunks, both in CLAUDE.md. The first hunk changes step 1 of the New Endpoint Implementation Workflow to point at the wiki page instead of the legacy API docs. The second hunk rewrites the REST API Documentation section, which the linked issue targets. The workflow change is not listed in
#1692. It applies the same source-of-truth rule within the same file, and without it the workflow would still send endpoint research to the legacy docs first. The legacy URL is kept as a reference in the REST API section. No unrelated code, configuration, or test changes appear in the diff. The change is documentation only, consistent with the PR description.
Full details: Docstring Coverage
-
Explanation
No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
|
The description follows the PR template. |
Ahmedhossamdev
left a comment
There was a problem hiding this comment.
@chikolavosaki-sys thanks, this is a clear rewrite and the trips-for-route example checks out against Java and the wiki. Looks good to me. Two small wording points inline: the /api/ondemand example isn't on main yet, and the text doesn't say what to do when an endpoint has no wiki page. Either can be a follow-up.
| 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`. | ||
|
|
||
| **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. | ||
| 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/ondemand`) needs no openapi.yml entry, but the PR description must say why. |
There was a problem hiding this comment.
Oh yah.. , switched the example to /api/where/metrics.json.
| ## 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
Some endpoints, such as block and the report-problem endpoints, have no wiki page yet. Without a fallback, an agent may treat openapi.yml as the authority for them; say to follow the Java implementation and flag it in the PR instead. Use /api/where/metrics.json as the example of an endpoint outside the SDK. /api/ondemand only exists in open GTFS-Flex PRs, so it can't be found on main.
Ahmedhossamdev
left a comment
There was a problem hiding this comment.
LGTM @chikolavosaki-sys
|



Fixes #1692
What it does
Rewrites the REST API Documentation section of CLAUDE.md so the maglev.wiki spec is the source of truth and openapi.yml comes second, as suggested in #1692. Also points step 1 of the New Endpoint Implementation Workflow at the wiki instead of the legacy API docs. Docs only.
Root cause
CLAUDE.md said every endpoint "MUST behave identically" to openapi.yml and that "the spec wins". openapi.yml has known errors: its trips-for-route entry says
includeStatusandincludeScheduledefault to false (testdata/openapi.yml:613,:619), while Java and the wiki use true. Following the old rule produced PRs such as #1336 and #1649, which were closed for that reason. The rule also conflicted with the PR template's checklist item for endpoints outside the SDK.The new text:
Testing
mainbefore this change: n/a (documentation only)go vet(both tag sets),make testandgo fmt ./...pass.Checklist
Ready-for-review requirement: Every box must be checked. If any statement is not true, keep the pull request
as Draft.
mainand passes on this branch.gtfsdb/(db.go,models.go,query.sql.go) ortestdata/openapi.yml(synced from upstream).r.Context()to DB/service calls, notcontext.Background().testdata/openapi.yml, has an issue open on OneBusAway/sdk-config, or is outside the SDK and the description says why.Notes for reviewers (optional)
Summary by CodeRabbit