Problem description
None of NAM's list endpoints implement the pagination model defined in Commonalities r4.2 §4.1. Affected endpoints (all return bare arrays today):
GET /trust-domains → TrustDomainList is type: arrayGET /trust-domains/{id}/devices → TrustDomainDeviceList is type: arrayGET /network-access-devices → NetworkAccessDeviceList is type: arrayGET /reboot-requests → RebootRequestList is type: arrayGET /services → ServiceList is type: array
None declare page / perPage query parameters, none wrap the response in a Pagination object, and none emit the r4.2 response headers (X-Total-Count, X-Total-Pages, Link).
Per the r4.2 API Design Guide §4, pagination is "MAY optionally be supported by the API provider" — so non-adoption is not strictly a guideline violation. But §4 also flags the rationale: list endpoints can return arbitrarily large result sets, posing performance and DoS-mitigation concerns, and a client cannot tell from a bare array whether the result is complete or truncated.
With Commonalities being bumped from r3.4 to r4.2 (the r4.2 CAMARA_common.yaml introduces X-Total-Count, X-Total-Pages, and Link response header definitions plus Pagination / Page / PerPage / TotalCount / TotalPages schemas explicitly to support this), now is the natural inflection point to decide NAM's posture.
Possible evolution
Either path is consistent with r4.2 §4; the team needs to pick one.
-
Adopt pagination on all list endpoints. Apply the r4.2 §4.1 shape verbatim:
- Wrap each
*List schema as { items: [...], pagination: Pagination }
- Add
page (default 1) and perPage (default 20, max 100) query parameters to every list operation per §4.1.1
- Optionally emit the three response headers per §4.1.4
- Return
200 with empty items: [] for both empty-collection and out-of-range-page cases per §4.1.5
- Reuse the r4.2 schemas at artifacts/common/CAMARA_common.yaml (
Pagination, Page, PerPage, TotalCount, TotalPages, plus the three response headers x-total-count, x-total-pages, link)
-
Document explicit opt-out. Add a paragraph to info.description (and/or each list operation) stating that NAM list endpoints return full collections because per-subscriber cardinality is expected to remain modest — a typical subscriber has a handful of Trust Domains, tens of devices, and a small number of in-flight Reboot Requests. Per §4 this is acceptable, but it should be made explicit so consumers don't assume r4.2-style pagination is available.
The per-subscriber cardinality argument leans toward option 2 for most NAM lists. The wrinkle is :read-all-scoped reads: a NaaS aggregator or property manager viewing the federated set across many API clients (or, prospectively, many subscribers) could land in cardinality territory where option 1 starts to matter.
Alternative solution
Hybrid — pagination ON for :read-all-scoped operations (federated/aggregator reads) and OFF for the default per-subscriber reads. Cleaner in theory but adds an asymmetry that's hard to test and document; probably not worth the seam unless one of the federated/portability use cases makes it clearly necessary.
Additional context
Problem description
None of NAM's list endpoints implement the pagination model defined in Commonalities r4.2 §4.1. Affected endpoints (all return bare arrays today):
GET /trust-domains→TrustDomainLististype: arrayGET /trust-domains/{id}/devices→TrustDomainDeviceLististype: arrayGET /network-access-devices→NetworkAccessDeviceLististype: arrayGET /reboot-requests→RebootRequestLististype: arrayGET /services→ServiceLististype: arrayNone declare
page/perPagequery parameters, none wrap the response in aPaginationobject, and none emit the r4.2 response headers (X-Total-Count,X-Total-Pages,Link).Per the r4.2 API Design Guide §4, pagination is "MAY optionally be supported by the API provider" — so non-adoption is not strictly a guideline violation. But §4 also flags the rationale: list endpoints can return arbitrarily large result sets, posing performance and DoS-mitigation concerns, and a client cannot tell from a bare array whether the result is complete or truncated.
With Commonalities being bumped from r3.4 to r4.2 (the r4.2 CAMARA_common.yaml introduces
X-Total-Count,X-Total-Pages, andLinkresponse header definitions plusPagination/Page/PerPage/TotalCount/TotalPagesschemas explicitly to support this), now is the natural inflection point to decide NAM's posture.Possible evolution
Either path is consistent with r4.2 §4; the team needs to pick one.
Adopt pagination on all list endpoints. Apply the r4.2 §4.1 shape verbatim:
*Listschema as{ items: [...], pagination: Pagination }page(default 1) andperPage(default 20, max 100) query parameters to every list operation per §4.1.1200with emptyitems: []for both empty-collection and out-of-range-page cases per §4.1.5Pagination,Page,PerPage,TotalCount,TotalPages, plus the three response headersx-total-count,x-total-pages,link)Document explicit opt-out. Add a paragraph to
info.description(and/or each list operation) stating that NAM list endpoints return full collections because per-subscriber cardinality is expected to remain modest — a typical subscriber has a handful of Trust Domains, tens of devices, and a small number of in-flight Reboot Requests. Per §4 this is acceptable, but it should be made explicit so consumers don't assume r4.2-style pagination is available.The per-subscriber cardinality argument leans toward option 2 for most NAM lists. The wrinkle is
:read-all-scoped reads: a NaaS aggregator or property manager viewing the federated set across many API clients (or, prospectively, many subscribers) could land in cardinality territory where option 1 starts to matter.Alternative solution
Hybrid — pagination ON for
:read-all-scoped operations (federated/aggregator reads) and OFF for the default per-subscriber reads. Cleaner in theory but adds an asymmetry that's hard to test and document; probably not worth the seam unless one of the federated/portability use cases makes it clearly necessary.Additional context
artifacts/common/CAMARA_common.yamlif option 1 is pursued.Linkheader for pagination navigation is a narrower, RFC 8288-shaped subset of the broader HATEOAS concept Add HATEOAS links #12 explores).