docs: add API v2 reference and split api-reference into v1/v2#303
Open
sriramveeraghanta wants to merge 2 commits into
Open
docs: add API v2 reference and split api-reference into v1/v2#303sriramveeraghanta wants to merge 2 commits into
sriramveeraghanta wants to merge 2 commits into
Conversation
Adds the full Plane API v2 reference and restructures /api-reference/ into explicit version folders, with v2 positioned as the current, recommended API. Structure - Move the existing 270 v1 pages to docs/api-reference/v1/ (git-tracked renames) - Add docs/api-reference/v2/ with 115 pages: 88 endpoint pages covering every v2 operation, 19 resource overviews, and 8 concept guides - Nav becomes a version switcher: v2 (latest) / v1 (legacy) - Rewrite 284 internal links to the versioned paths Routing - /api-reference and /api-reference/introduction now land on v2 - Legacy deep links fall through to their v1 equivalents via a ((?!v1/|v2/).*) catch-all ordered after the specific legacy redirects, so previously indexed URLs keep working - docs/api-reference/index.md covers `pnpm dev`, where vercel.json redirects do not run - Widen the theme's api-page layout check so v2 prose guides keep the standard doc layout Coverage - Work items (incl. archive/unarchive and PROJ-123 identifier lookup), comments, states, labels, cycles, modules - Work item types, custom properties, property options and property contexts, at both project and workspace level, plus the mode-gating rules - Workspace features, members, audit logs, users/me - Concept guides: authentication and OAuth scopes, pagination, filtering and ordering, expanding relations, RFC 9457 errors, type modes, and a v1->v2 migration guide Pages were verified against the committed OpenAPI golden file for parameter names, types, enums, required flags, scopes and status codes, and against the api_v2 source where the schema under-describes actual behavior. Claude-Session: https://claude.ai/code/session_01J8k8wr7tWTXcAGKsprAYyq
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedToo many files! This PR contains 394 files, which is 294 over the limit of 100. To get a review, narrow the scope: Upgrade to a paid plan to raise the limit. Usage-priced reviews support at most 300 files. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (394)
You can disable this status message by setting the ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
The header "API Reference" link now goes straight to v2. Version switching lives at the top of the API reference sidebar, and selecting a version swaps the whole sidebar tree via the existing path-prefix keys. Implemented as two links rather than a <select>: Vue's SSR drops `selected` on options inside a bound select, so a dropdown renders the wrong version before hydration and does not work at all without JS. Links are correct on first paint and degrade cleanly. - Add ApiVersionSwitcher.vue, injected through the sidebar-nav-before slot; it hides itself outside /api-reference/ - Header nav: dropdown -> single link to /api-reference/v2/introduction - Drop the now-redundant version suffixes from sidebar group titles Claude-Session: https://claude.ai/code/session_01J8k8wr7tWTXcAGKsprAYyq
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the full Plane API v2 reference and restructures
/api-reference/into explicit version folders, with v2 positioned as the current, recommended API.What changed
Structure
docs/api-reference/v1/— git-tracked as renames, so history is preserveddocs/api-reference/v2/with 115 pages: 88 endpoint pages (every v2 operation), 19 resource overviews, 8 concept guides<select>: Vue's SSR dropsselectedon options inside a bound select, so a dropdown would render the wrong version before hydration and wouldn't work at all without JSRouting — the unversioned entry point lands on v2, and no previously indexed URL 404s:
/api-reference/api-reference/v2/introduction/api-reference/introduction/api-reference/v2/introduction/api-reference/issue/overview(legacy deep link)/api-reference/v1/issue/overviewThe legacy catch-all is
/api-reference/:path((?!v1/|v2/).*), ordered after the specificcycle-issue/module-issueredirects so those still win.docs/api-reference/index.mdcoverspnpm dev, wherevercel.jsonredirects don't run.Coverage
PROJ-123identifier lookup), comments, states, labels, cycles, modulesusers/meHow accuracy was established
The OpenAPI golden file (
openapi-v2.json) was resolved into per-operation specs, and every page checked against them for parameter names, types, enums, required flags, scopes and status codes. A verification pass then re-checked each page adversarially. Automated check: 88/88 operations have a page with the correct method badge and exact path; sidebar and disk agree at 115 ↔ 115 with no orphans.check:types,check:format, andvitepress buildall pass, with no dead links.Follow-ups for the API team (not addressed here)
The schema under-describes actual behavior in four places. The docs follow the source; the schema is what needs fixing:
?expand=is implemented (core/views.py_expand()) but declared on no operation. Only work items (state,type,parent,assignees,labels) and members (member) support it.?cursor=is a real parameter (core/views.py:192) but undeclared.200/401/403/404/429, yet genuinely return400for invalid filter enums andordering_not_cursor_eligible.AuditLog.project_idis nullable in the model but the schema omitsnullable: true.Also worth noting for anyone reading the source docs:
order_byandpaginateare not validated — an unknown value silently falls back (OrderingSpec.resolve(),views.py:192) — while filter enums backed by aChoiceFilter(choices=…)genuinely do return400. The pages distinguish these two cases per resource. Separately,docs/api_v2/API_USAGE.mdinplane-eehas a stale endpoint catalog (no types, properties, features, or audit logs).Review notes
Two judgment calls worth a look:
/api-reference/introductionsends readers to v2 rather than v1, treating it as the versionless front door. Easy to flip if you'd rather it stay on v1.?expand=is documented despite its absence from the schema, since the code supports it.https://claude.ai/code/session_01J8k8wr7tWTXcAGKsprAYyq