docs: Add REST endpoint guidance by kfelternv · Pull Request #3031 · NVIDIA/infra-controller

kfelternv · 2026-06-30T16:32:48Z

Add some specific guidance to the agents.md file for development work against the REST api for NICo

copy-pr-bot · 2026-06-30T16:32:51Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

coderabbitai · 2026-06-30T16:32:57Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 40183c3a-851c-4b2b-9d43-a25c2ba404f8

📥 Commits

Reviewing files that changed from the base of the PR and between f1db5cd and a778d70.

📒 Files selected for processing (1)

rest-api/AGENTS.md

💤 Files with no reviewable changes (1)

rest-api/AGENTS.md

Summary by CodeRabbit

Documentation
- Updated API guidance to keep published API docs aligned with the public REST surface.
- Clarified consistent naming and response rules for endpoints and resources.
- Added broader best practices for route organization, request validation, pagination, and handling sensitive data in responses and logs.
- Expanded testing expectations for API changes to improve reliability and consistency.

Walkthrough

This PR updates rest-api/AGENTS.md documentation, revising OpenAPI update scope guidance, introducing standardized naming conventions for handlers/models, adding a "REST endpoint implementation patterns" section covering endpoint families and handler thin-layer conventions, and expanding the endpoint testing checklist.

Changes

REST endpoint guidance

Layer / File(s)	Summary
OpenAPI update scope and naming conventions `rest-api/AGENTS.md`	Reworks OpenAPI update trigger to the published API surface, adds handler/DTO/model naming prefixes, ID placement rules, and revised success-response/redaction guidance.
Endpoint patterns, public routes, and model conventions `rest-api/AGENTS.md`	Adds reference endpoint families (DB triplets, site-scoped, Flow-backed, Core unary), `.well-known/*` route placement, `FromDBModel`/`ToDBModel` naming, and REST route/pagination conventions.
Handler and transaction conventions `rest-api/AGENTS.md`	Adds "keep handlers thin" checklist covering auth/validation, conversion trust boundaries, `cdb.WithTx`/`WithTxResult` transaction patterns, Temporal workflow reuse, redaction, and route-registration ordering rules.
Route registration and testing checklist `rest-api/AGENTS.md`	Adds testing checklist for model validation/mappings, handler auth/status/response-shape, pagination headers, and secret-absence assertions in responses and logs.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly reflects the main change: adding REST endpoint guidance to documentation.
Description check	✅ Passed	The description is directly related to the REST API guidance added in agents.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands.}

thossain-nv · 2026-06-30T16:50:00Z

This is great @kfelternv A few other things to add:

FromDBModel (we want to transition from NewX to this receiver) and ToDBModel for converting between APi and DB models
All API model attributes should be structured, we don't allow schemaless JSON exposure. JSON tags must be camel Case. All constants should be in Pascal Case.
Implementor should seek observe all existing endpoint routes to make the best decision for a new route. Naming the route and attributes correctly is critical, once published in a release tag it must use deprecation to In general we follow REST best practices:
- Creating new objects should be done using POST
- Updates should be done using PATCH
- PUT is used only if the endpoint supports both creation or update
- Unless the resource has no unique identifier, PATCH, GET and DELETE routes must end with resource ID
- GET requests that return multiple objects must return pagination information in designated pagination header in response

github-actions · 2026-07-01T15:05:36Z

🔍 Container Scan Summary

Service	Total	Critical	High	Medium	Other
nico-flow	12	1	2	2	7
nico-nsm	4	0	0	4	0
nico-psm	12	1	2	2	7
nico-rest-api	12	1	2	2	7
nico-rest-cert-manager	12	1	2	2	7
nico-rest-db	12	1	2	2	7
nico-rest-site-agent	12	1	2	2	7
nico-rest-site-manager	12	1	2	2	7
nico-rest-workflow	12	1	2	2	7
TOTAL	100	8	16	20	56

Per-CVE detail lives in the per-service grype-* artifacts (JSON + SARIF). Severity counts only — no CVE IDs published here.

github-actions · 2026-07-01T15:06:07Z

🌿 Preview your docs: https://nvidia-preview-pull-request-3031.docs.buildwithfern.com/infra-controller

github-actions · 2026-07-01T15:07:13Z

🔐 TruffleHog Secret Scan

✅ No secrets or credentials found!

Your code has been scanned for 700+ types of secrets and credentials. All clear! 🎉

🔗 View scan details

_{🕐 Last updated: 2026-07-01 15:07:13 UTC | Commit: d1412af}

coderabbitai

🧹 Nitpick comments (2)

rest-api/AGENTS.md (2)
270-281: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add the pagination response-header contract to the checklist.

The checklist covers paging inputs, but not the response-side pagination header required for multi-object GETs in the PR objectives. Call that out here so endpoint authors assert the full contract, not just request validation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rest-api/AGENTS.md` around lines 270 - 281, The endpoint testing checklist is
missing the response-side pagination header contract for multi-object GETs, so
update the guidance in AGENTS to explicitly require asserting the pagination
header behavior as part of endpoint tests. Add this alongside the existing
paging input checks so authors cover both request validation and response
headers, especially in the sections covering handler tests and route/OpenAPI
coverage.
267-269: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Scope the OpenAPI requirement to published routes.

This reads like every new route must update openapi/spec.yaml, but the same section explicitly exempts system/public discovery routes from NewAPIRoutes. Tighten it to routes that are actually part of the OpenAPI surface.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rest-api/AGENTS.md` around lines 267 - 269, Tighten the OpenAPI update
requirement in AGENTS.md so it applies only to routes that are actually
published in the OpenAPI surface, not every new route. Clarify the guidance
around NewAPIRoutes by explicitly exempting system/public discovery routes and
any other non-OpenAPI endpoints, while still requiring openapi/spec.yaml updates
for documented API routes. Keep the instruction aligned with the existing
references to openapi/spec.yaml, NewAPIRoutes, and the SDK-facing naming
guidance.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@rest-api/AGENTS.md`:
- Around line 270-281: The endpoint testing checklist is missing the
response-side pagination header contract for multi-object GETs, so update the
guidance in AGENTS to explicitly require asserting the pagination header
behavior as part of endpoint tests. Add this alongside the existing paging input
checks so authors cover both request validation and response headers, especially
in the sections covering handler tests and route/OpenAPI coverage.
- Around line 267-269: Tighten the OpenAPI update requirement in AGENTS.md so it
applies only to routes that are actually published in the OpenAPI surface, not
every new route. Clarify the guidance around NewAPIRoutes by explicitly
exempting system/public discovery routes and any other non-OpenAPI endpoints,
while still requiring openapi/spec.yaml updates for documented API routes. Keep
the instruction aligned with the existing references to openapi/spec.yaml,
NewAPIRoutes, and the SDK-facing naming guidance.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: af1d553a-4632-444f-9f9b-0c3153fc473c

📥 Commits

Reviewing files that changed from the base of the PR and between 6cbe4cc and d1412af.

📒 Files selected for processing (1)

rest-api/AGENTS.md

thossain-nv · 2026-07-07T23:24:55Z

Making a few final tweaks to the instructions, will merge afterwards.

Signed-off-by: Kyle Felter <[email protected]>

thossain-nv

Thanks for this @kfelternv

kfelternv marked this pull request as ready for review July 1, 2026 15:04

kfelternv requested a review from a team as a code owner July 1, 2026 15:04

kfelternv requested a review from thossain-nv July 1, 2026 15:04

coderabbitai Bot reviewed Jul 1, 2026

View reviewed changes

kfelternv added the low risk label Jul 1, 2026

thossain-nv reviewed Jul 1, 2026

View reviewed changes

Comment thread rest-api/AGENTS.md

kfelternv enabled auto-merge (squash) July 7, 2026 13:01

kfelternv requested review from Coco-Ben and thossain-nv July 7, 2026 13:01

ajf removed the low risk label Jul 7, 2026

ajf removed the request for review from Coco-Ben July 7, 2026 20:20

kfelternv and others added 6 commits July 8, 2026 18:40

docs: Add REST endpoint guidance

0670f2c

Signed-off-by: Kyle Felter <[email protected]>

docs: Add REST endpoint guidance

7d26790

chore: Ignore local workspace files

fde42cd

docs: Refine REST endpoint guidance

2abde57

chore: Remove unrelated ignore entries

9b5116b

Enhance API handler/model design instructions

a778d70

thossain-nv force-pushed the agents-rest-api-guidance branch from 875cd17 to a778d70 Compare July 9, 2026 01:40

thossain-nv approved these changes Jul 9, 2026

View reviewed changes

thossain-nv disabled auto-merge July 9, 2026 16:27

thossain-nv merged commit b907061 into NVIDIA:main Jul 9, 2026
119 checks passed

coderabbitai Bot mentioned this pull request Jul 10, 2026

fix: Align v2.0 behavior and documentation #3321

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Add REST endpoint guidance#3031

docs: Add REST endpoint guidance#3031
thossain-nv merged 6 commits into
NVIDIA:mainfrom
kfelternv:agents-rest-api-guidance

kfelternv commented Jun 30, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Jun 30, 2026

Uh oh!

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

thossain-nv commented Jun 30, 2026

Uh oh!

github-actions Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 1, 2026

Uh oh!

github-actions Bot commented Jul 1, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

thossain-nv commented Jul 7, 2026

Uh oh!

thossain-nv left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

kfelternv commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

copy-pr-bot Bot commented Jun 30, 2026

Uh oh!

coderabbitai Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

thossain-nv commented Jun 30, 2026

Uh oh!

github-actions Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Container Scan Summary

Uh oh!

github-actions Bot commented Jul 1, 2026

Uh oh!

github-actions Bot commented Jul 1, 2026

🔐 TruffleHog Secret Scan

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thossain-nv commented Jul 7, 2026

Uh oh!

thossain-nv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kfelternv commented Jun 30, 2026 •

edited

Loading

coderabbitai Bot commented Jun 30, 2026 •

edited

Loading

github-actions Bot commented Jul 1, 2026 •

edited

Loading