Enhancement Proposal – Standardizing Limited Success Response Handling

[shilpa-padgaonkar]

Problem description
The current CAMARA API Design Guide does not explicitly define or standardize handling for limited success response cases (informative 2xx responses). These responses represent successful operations with partial fulfillment due to factors such as user preferences or temporary subject unavailability.

As a result, CAMARA APIs currently adopt inconsistent patterns when reporting scenarios like privacy control limitations or subject context restrictions. This inconsistency complicates both client implementation and interoperability across APIs that need to express partial but valid outcomes.

Possible evolution
Enhance the CAMARA API Design Guide to define and standardize a Success-Limited Payload model that can be reused across all APIs. The enhancement would:

• Introduce a unified schema to represent limited success outcomes under CAMARA_common.yaml.
• Define an explicit discriminator type for limited success cases:
  • SUBJECT_CONTEXT — indicates a limitation based on contextual or operational factors (e.g., device unreachable, not processable etc.).
• Provide guidance on client handling logic for each type (e.g., retry on SUBJECT_CONTEXT).
• Document example 200 responses for these cases.

This addition would ensure all APIs follow a consistent and auditable structure when returning success-limited responses.

Alternative solution
Each API could define its own approach to represent limited success conditions within its schema definitions. However, this would lead to divergence across subprojects and reduced interoperability. Additionally, such ad-hoc implementations would make automated client generation and validation more complex.

By introducing a standardized model and adding a normative section (proposed as 2.3 Limited Success Responses) in the Design Guide, CAMARA can provide a unified pattern that is simple to extend and maintain.

Additional context
This issue proposes an enhancement to the CAMARA API Design Guide and the associated CAMARA_common.yaml artifact to include standardized limited success response handling.

Example limited success cases:

• SUBJECT_CONTEXT → notReachable, notProcessable

The goal is to support context-based partial outcomes under a single reusable schema, ensuring consistent interpretation by SDKs and API consumers.

cc @gmuratk

[Kevsy]

HI @shilpa-padgaonkar , that's interesting - have you any examples you could share using an existing CAMARA API?

Overall I think there could be a distinction between:

• an operation on a single resource, where the desired outcome is partially achieved
• a batch operation on a resource collection, with mixed success across the resources involved.

Certainly in any case it makes sense for the API consumer do know whether there is any modification needed in their request before retrying it.

[gmuratk]

Hi @Kevsy
I can point to an example that appeared in a community discussion in DeviceStatus subproject back in December 2023, there was a debate about the correct handling of cases where device is not connected to the network while querying its roaming status.
Several viewpoints emerged:

• Using HTTP 503 (UNAVAILABLE) was considered misleading since the server itself was operational and capable of responding.
• HTTP 404 (NOT FOUND) was also deemed inappropriate because the device was identified successfully; it was simply not attached to the network at that time.
• The conclusion favored returning a 200 OK response with an additional payload indicator (e.g., connectivityStatus: "no"), representing a limited success — the request was valid, but the desired data (e.g., current roaming state) could not be fully determined.

[PedroDiez]

Hi,

@shilpa-padgaonkar, @gmuratk I would like to understand in more detail the rationale under this proposal.

1. Which use cases do you envision to be cover by this proposal? Do you see it for APIs with device concept?
   For instance in Device Reachabiluty Status there is the field "reachable" that in case the device is not connected response would be false.

2. Think as far as possible look for backwards compatibility would be a goog point.

3. The use of 200 OK HTTP code could be somehow misleading. I will comment within the PR proposal

[shilpa-padgaonkar]

Hi @PedroDiez — thanks for the questions. Yes, APIs with device concepts are one category of use cases (e.g., reachability/connection state). The other category is policy/business constraints, such as “do-not-sell” scenarios, where the request is valid but fulfillment is limited by business rules.
We agree backward compatibility is important and are open to refining the response pattern so it’s clear and not misleading (incl. the discussion around 200 OK). Happy to iterate in the PR.

[Elisabeth-Mueller]

Hi @PedroDiez; @shilpa-padgaonkar,
I think that we will need such an enhancement for upcoming use cases for group management.
Also, when it comes to partial success or failure due to subject context and not due to technical issues we need it.

@PedroDiez: I wonder which response code family do you propose ? I checked RFC 7231 again. It states that HTTP response codes 4xx shall be used for client errors. But the use case above is not an error on the request the client is making. And the server accepts the request and processes it. To me it looks like the response code family 2xx is the most appropriate, but for sure with enhanced information in case of "partial success/execution" due to context constraints. What is your proposal ?