Repository navigation
Conversation
Add an API Conventions guide with a Sparse fieldsets section and register it in the guides sidebar. Co-authored-by: Cursor <cursoragent@cursor.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 0c4c91f. Configure here.
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Publication depends on confirming deployment of the inaccessible vertex-api#810 behavior change.
Review effort: Balanced
Findings: None
What changed in this PR
Adds a public API conventions guide documenting JSON:API sparse fieldsets and registers it in the Reference sidebar.
Changes:
- Documents sparse-fieldset parsing, defaults, and request-only fields.
- Explains the temporary
fields[thread]exception. - Adds the guide to navigation.
| File | Description |
|---|---|
docs/guides/api-conventions.mdx |
Adds the API conventions guide. |
sidebars.js |
Registers the guide under Reference. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Cursor <cursoragent@cursor.com>
Response to the review round on 0c4c91f:
Validation on 6f6848d: |
|
SonarCloud quality gate on 6f6848d: passed with 0 new issues and 0 security hotspots. No change needed. |
Agent:(claude-opus-5.5)Summary
Adds a public API Conventions guide,
docs/guides/api-conventions.mdx. It states that the Vertex Platform API follows JSON:API and gives the sparse fieldset rules in one place, so the API Reference, support, and Jira can link to them. It is part of PLAT-9548.The Sparse fieldsets section, at the stable anchor
#sparse-fieldsets, states:fields[<type>]takes a comma-separated list of field names.metadata) are returned only when requested.fields[thread]only opts intoreplyCountand doesn't restrict other thread fields. This matchesThreadRouter.replyCountFieldMaskin vertex-api. Remove the note when PLAT-9551 ships. That is the coordinatedfields[thread]rollout, and its vertex-api change is PLAT-9550.The page is registered in
sidebars.js(guidesSidebar, Reference category).guides.jsisn't used by the site, so it isn't changed.Expected URL once deployed: https://developer.vertex3d.com/docs/guides/api-conventions#sparse-fieldsets
Test Plan
yarn install --frozen-lockfileandyarn build: passed. Docusaurus generatedbuild/docs/guides/api-conventions/index.html.id="sparse-fieldsets", and other guide pages' sidebars link to/docs/guides/api-conventions.''(docusaurus.config.js), so the page publishes at/docs/guides/api-conventions, not under a version prefix.prettier --checkon the changed files andyarn lint: passed.fields[thread]behavior were checked againstsrc/universal/api.ymlandThreadRouter.scalaon the vertex-api#810 branch.Release Notes
New developer guide: API Conventions explains how sparse fieldsets (
fields[<type>]) select the fields returned by Platform API responses.Possible Regressions
fields[scene]=name, createddon't match. The comma-only empty valuefields[scene]=,is also wrong until then, because it still returns every field. See Dependencies.Dependencies
fields[...]parameter descriptions to this page's#sparse-fieldsetsanchor, so the anchor must stay stable.Related
fields[thread]conformance)Note
Low Risk
Documentation and sidebar navigation only; no runtime or API code changes.
Overview
Adds a new API Conventions developer guide that documents JSON:API usage on the Platform API and centralizes sparse fieldset behavior for
fields[<type>](comma lists, whitespace, empty values, case sensitivity, opt-in fields likemetadata, and default fields when omitted). Includes acurlexample and a note thatfields[thread]only opts intoreplyCountwithout restricting other thread fields.Registers the page at the top of the Reference section in
sidebars.jsso it publishes at/docs/guides/api-conventionswith anchor#sparse-fieldsetsfor cross-links from the API Reference.Reviewed by Cursor Bugbot for commit 6f6848d. Bugbot is set up for automated code reviews on this repo. Configure here.