Implicit-subscription template: document unavailability signalling and clarify implementation-side opt-out

[hdamker]

Problem description

The implicit-subscription API template (sample-implicit-events.yaml lines 291-312) makes sink optional on the response Resource schema. When a consumer supplies a valid sink on the create-resource request, today's only way for an implementation to signal "I created the resource but I'm not delivering events" is to omit sink from the 200/201 response body — the resource itself is still created with success status. Two gaps follow:

1. Implementation-side opt-out is undefined. The guideline doc (§2.1, line 60) says an API project's choice to offer the implicit-subscription pattern is OPTIONAL. It does not address whether a specific implementation of an API that does offer the pattern may decline event delivery for a given request.
2. Unavailability signal is undocumented. The sink-omission convention is not written down anywhere — neither in the template nor in the guideline doc.

CAMARA-API-Design-Guide.md §3.1.3 "Recommended Modeling Pattern" already provides a fitting framework: the "Nullability/presence rules" approach lets the domain-specific outcome field (here, sink echoed in the response) carry the primary signal, with optional contextCode / contextMessage for explanation. Sink-omission is therefore design-guide-compliant Limited Success on 2xx; it just isn't tied back to §3.1.3 anywhere on the implicit-subscription side.

Possible evolution

Working group decision needed: may an implementation of an implicit-subscription-offering API decline event delivery when the consumer supplies a valid sink? If yes:

1. Document the sink-omission contract explicitly in both:
   • The template's Resource.sink description (lines 306-312) — state that sink-omission in the response when sink was supplied in the request indicates event delivery is unavailable.
   • The guideline doc (§2.1) — cross-reference §3.1.3 of the Design Guide as the rationale.
2. RECOMMEND (not mandate) the optional contextCode / contextMessage fields per Design Guide §3.1.3 to explain why event delivery is unavailable. Non-breaking for clients.

A follow-up PR can land both changes after the WG decision.

Alternative solution

Forbid implementation-side opt-out: every implementation of an API offering the implicit-subscription pattern MUST deliver events when a valid sink is supplied. Then sink becomes required in the response (when present in the request), and unavailability moves to a 4xx or 5xx error path. Cleaner contract, but a step further from current implementations.

Additional context

• Related: #589 (Business-Level Outcome 2xx vs 4xx scenarios) — the Design Guide §3.1.3 framework that this issue would consume.
• Related: #612 (the implicit-subscription template that this issue refines).
• Cross-reference filed on QualityOnDemand: QualityOnDemand#556.

[PedroDiez]

From our perspective in TEF, we consider better the alternative solution. Our rationale is the following:

• sink is optional in the response, coherently with its optionality in the request (that was the principle design when this feature was modelled)
• When sink is provided in the request by API Consumer, it implicitly means that the implicit subscription model is requested (i.e., to receive event notifications).
• Then, when the sink (i.e. implicit subscription model) is not supported by an API Provider, returning an error makes clear to API Consumer the situation and ease API Developers to manage it (e.g. for instance, to make fallback for a polling solution GET /, when defined in the API)

[hdamker]

Agreed with @PedroDiez — going with the Alternative solution from the issue description rather than the sink-omission model.

To restate the contract: implementations SHOULD support event delivery for a valid sink. If sink is supplied and delivery can't be supported, the implementation MUST respond with an error rather than create the resource with sink silently omitted.

Malformed/invalid sink itself is already covered by the template's existing client-fault codes (400 INVALID_SINK / INVALID_PROTOCOL / INVALID_CREDENTIAL) — no change needed there. But "the provider doesn't support notification delivery at all" is a different case: there's nothing the consumer can do to fix it, so this reads to me as a 5xx, not a 4xx. 501 NOT_IMPLEMENTED is tempting, but as currently scoped in the Design Guide it's meant for a whole endpoint/functionality being unimplemented — not obviously right for one optional capability within an otherwise-working operation.

So: what concrete status/code should represent "this API provider does not support notification delivery"? Opening that to the group rather than picking one myself — a narrower 501 with a specific code, a plain 500/503 with a dedicated code, or something else.

I would propose to document the SHOULD-support / MUST-error-if-declined contract in the template's Resource.sink description and guideline doc §2.1, once we've settled on the concrete signal above.

[PedroDiez]

Would propose to define a new 422 code NOTIFICATIONS_NOT_SUPPORTED or NOTIFICATIONS_DELIVERY_NOT_SUPPORTED

[hdamker]

@PedroDiez I agree with 422 (client can react on it and retry without providing sink in the request). Would be great if you can provide the PR with this and the documentation changes.