docs: Add REST endpoint guidance

[kfelternv]

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

[copy-pr-bot]

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]

Summary by CodeRabbit

• Documentation
  • Added guidance for implementing REST endpoints, including patterns to follow, route placement, handler structure, and security considerations.
  • Expanded testing expectations for endpoint changes, covering validation, authorization, response shape, and error handling checks.

Walkthrough

This PR adds a new "REST endpoint implementation patterns" subsection to rest-api/AGENTS.md. It documents reference endpoint families to mirror, handler construction and route registration conventions, and testing expectations for REST endpoint changes. No code or exported entity changes are included.

Changes

AGENTS.md documentation update

Layer / File(s)	Summary
Reference endpoint families and routing guidance rest-api/AGENTS.md	Adds guidance on which existing endpoint family shapes to copy (DB-backed, site-scoped, Flow-backed, NICo Core unary), public discovery routing placement for .well-known/*, and when to use the common gRPC proxy execution helper.
Handler and route registration conventions rest-api/AGENTS.md	Documents common.SetupHandler usage, DTO Validate enforcement, lookup helper standardization, ToProto/FromProto placement, transaction/error translation patterns, Temporal workflow ID/timeout/termination reuse, response redaction constraints, and NewAPIRoutes registration/ordering rules.
Endpoint testing checklist rest-api/AGENTS.md	Adds a checklist covering model validation/mapping tests, handler auth/ownership/validation/response-shape checks, workflow/proxy argument and secret-absence assertions, and route test/OpenAPI alignment requirements.

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

Related issues: None referenced in the provided context.

Related PRs: None referenced in the provided context.

Suggested labels: documentation

Suggested reviewers: None can be determined from the provided context.

As a Principal Engineer, I note this change is confined entirely to documentation — a low-risk, well-structured addition that codifies existing conventions rather than altering behavior. No structural or logic concerns apply here; the prose is clear and the checklist format is appropriately actionable for future contributors.

A rabbit hops through docs at night,
Writing rules to keep code tight —
Handlers thin, transactions clean,
No secrets leaked in the JSON scene.
With checklists set and patterns clear,
Future PRs shall have less to fear. 🐇📜

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the documentation update adding REST endpoint guidance.
Description check	✅ Passed	The description is directly related to the AGENTS.md REST API guidance update.
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]

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]

🔍 Container Scan Summary

Service	Total	Critical	High	Medium	Low	Other
nico-flow	13	1	2	2	1	7
nico-nsm	50	0	10	32	8	0
nico-psm	13	1	2	2	1	7
nico-rest-api	13	1	2	2	1	7
nico-rest-cert-manager	12	1	2	2	0	7
nico-rest-db	13	1	2	2	1	7
nico-rest-site-agent	12	1	2	2	0	7
nico-rest-site-manager	12	1	2	2	0	7
nico-rest-workflow	13	1	2	2	1	7
TOTAL	151	8	26	48	13	56

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

[github-actions]

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

[github-actions]

🔐 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]

Let's add the suggestions I made in the comment here #3031 (comment)