docs(developer-docs): add API v2 reference and split api-reference into v1/v2 - #497
Draft
sriramveeraghanta wants to merge 3 commits into
Draft
docs(developer-docs): add API v2 reference and split api-reference into v1/v2#497sriramveeraghanta wants to merge 3 commits into
sriramveeraghanta wants to merge 3 commits into
Conversation
…to v1/v2 Port makeplane/developer-docs#303 into the monorepo. Structure - The 270 existing v1 pages move to docs/api-reference/v1/ (git-tracked renames, history preserved). - New docs/api-reference/v2/ with 463 pages: endpoint pages for every v2 operation, resource overviews, and nine concept guides. - Header "API Reference" goes to v2; version switching lives at the top of the API reference sidebar and swaps the whole sidebar tree. - Internal links rewritten to versioned paths. Routing — the unversioned entry point lands on v2 and no previously indexed URL 404s: /api-reference and /api-reference/introduction go to v2, and the catch-all /api-reference/:path((?!v1/|v2/).*) sends legacy deep links to v1, ordered after the specific cycle-issue/module-issue redirects so those still win. docs/api-reference/index.md covers `pnpm dev`, where vercel.json redirects don't run. Monorepo adaptations (upstream is a standalone repo) - The version switcher mounts through a new `layoutSlots` option on createPlaneTheme instead of the app forking the shared Layout, so packages/theme stays the single owner of layout composition. - Upstream's `packageManager` bump is dropped; the NODE_OPTIONS heap bump on the build script is kept, since the page count needs it. Also adds "sparse-fields" to the prose-page list, which upstream missed when a later commit added that concept guide — without it the page gets the wide two-column endpoint layout. Claude-Session: https://claude.ai/code/session_019kCVtLs1Yho8dzcuzV4Hrn
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
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 |
…EB-8669)
Brings the v2 reference up to the api_v2 surface on preview (80741805f7).
Coverage verified against the committed OpenAPI document: 406/406 operations
documented, no orphan pages, no duplicate coverage.
The committed spec on preview is already current — `check_v2_schema_drift
--check` reports "No schema drift", so no regen was needed this round.
## What changed upstream
WEB-8669 (#8946) **replaced the single `bulk/` route with three** and reshaped
the contract. Four api_v2 commits landed since the last sync; only this one
altered the public surface.
Removed (10 pages) — `POST …/<resource>/bulk/` no longer exists:
cycles, estimate points, estimates, labels, milestones, modules, projects,
states, work items, work item comments.
Added (29 pages) — `bulk-create/` and `bulk-update/` on all ten, plus
`bulk-delete/` on nine (projects has no bulk-delete).
## Contract changes documented
- **`all_or_none`** (default `false`) is the new atomic mode. Off, each row runs
in its own savepoint and successful rows commit. On, every row is still
evaluated — so you see everything that would fail, not just the first — and
then the whole batch is discarded with a `409`, `transaction.on_commit` side
effects included.
- **Cap is now 50 rows, was 100.** Exceeding it fails the envelope, not a row.
- **`bulk-update` items require `id`**; `bulk-delete` takes `{ids: [...]}`
rather than `items`.
- **The `upsert` flag is gone from bulk.** Reconciling on
`(external_source, external_id)` stays the single-row `upsert/` route's job.
- **Row shape**: success is `{index, result, id}` with `result` one of
`created`/`updated`/`deleted`; failure keeps the top-level problem members
(`type`, `code`, `detail`, `errors[]`) plus `index` and `result: "failed"`, so
the same error handling works per row as at the top level.
- **`200` does not mean every row succeeded** — each page says so up front, since
an empty-looking success is the easy mistake here.
- **JSON only**: the parsers are restricted, so a form or multipart body is a
clean `415` instead of `items` being silently misread.
- Bulk operations declare no `402`.
## Fixed: bulk-invitations documented the wrong contract
`POST …/invitations/bulk/` survived the rename because it is not the generic
mixin at all — `members_bulk` takes `{emails, role, message}`, caps at 100, is
atomic in one transaction, and answers `201` with the invitations it created.
The previous page described it as `{items}` with per-row results and an `upsert`
flag, none of which was ever true for this route. Rewritten from the view, and
it now documents the behavior that actually bites: **addresses with a pending
invite are skipped silently**, so the response array can be shorter than the
`emails` sent, or empty.
## Also
- 59 resource overviews: endpoint tables rebuilt from the page badges
- sparse-fields: the bulk exclusion now names the three routes
- sidebar regenerated from the page tree — 482 links, one per page
`check:format` (oxfmt), `check:types`, and `turbo run build` all pass. VitePress
fails on dead links, so the clean build is the link check; 844 pages render.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`AuditLogSourceEnum` gained `admin` in 17b1e49ab3 (#9071), which landed on preview after the last docs sync. The overview listed the five older values in two places; both now include `admin` and say what it means. Found by running the drift gate against the current preview tip rather than trusting the unchanged spec file: the committed openapi/ document is byte- identical between 80741805f7 and cb7ca630d6, but `check_v2_schema_drift --check` at cb7ca630d6 reports additive drift, and the one changed component is this enum. The spec regen for it belongs in a plane-ee PR and is not included here. Coverage re-verified against the regenerated spec at cb7ca630d6: 406/406 operations, no orphans. No operations were added or removed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
2 participants
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.
Ports makeplane/developer-docs#303 into this monorepo. 745 files, ~96k insertions.
Structure
apps/developer-docs/docs/api-reference/v1/— git-tracked as renames, so history is preserved.apps/developer-docs/docs/api-reference/v2/with 463 pages: an endpoint page per v2 operation, resource overviews, and nine concept guides.ApiVersionSwitcher.vue), and picking a version swaps the whole sidebar tree via the path-prefix keys inconfig.mts.<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 JS.Routing
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, and after/api-reference/byoa/build-plane-app.docs/api-reference/index.mdcoverspnpm devandpnpm preview, wherevercel.jsonredirects don't run.Monorepo adaptations
Upstream is a standalone repo, so three things could not be copied as-is:
sidebar-nav-beforeslot directly in the app's ownLayout. Here that layout lives inpackages/theme, so this adds alayoutSlotsoption tocreatePlaneTheme()and the app passes the switcher through it.packages/themestays the single owner of layout composition, per the monorepo rules.packageManagerbump is dropped — this workspace pins pnpm 11.8.0 at the root. TheNODE_OPTIONS=--max-old-space-size=8192bump on the build script is kept; the page count needs it./api-reference/…links rewritten in place. Verified: the monorepo sidebar and upstream's PR base are semantically identical (301 texts / 260 links), and both spliced sidebar trees match upstream's exactly.One fix on top of upstream
sparse-fieldswas missing from the prose-page list that decides which/api-reference/pages keep the normal doc layout. That concept guide was added by a later commit in the same PR and the list was never updated, so the page would render with the wide two-column endpoint layout. Added here — the list now covers all nine concept pages exactly.Verification
pnpm check:format— cleanpnpm check:types(theme + both apps) — cleanpnpm --filter developer-docs build— succeeds, 821 pages, no dead linksinbox-issue,work-item-relations) — confirmed identical onmaster, pre-existing, not introduced hereWorth a look
/api-reference/introduction(the versionless front door) resolves to v2, but in-page links on the home page and thebuild-plane-appguides were pointed at v1 by upstream. Ported faithfully; easy to flip if they should follow the front door to v2.?expand=even though it is absent from the OpenAPI schema, because the code supports it. Carried over as-is.?expand=and?cursor=, missing400on list operations, nullableAuditLog.project_id). Those are source-side, not doc-side, and are unaffected by this port.Draft while makeplane/developer-docs#303 is still under review.
https://claude.ai/code/session_019kCVtLs1Yho8dzcuzV4Hrn