CELDEV-1334 Add current-wiki REST reference ADR - #31
Conversation
0270c83 to
961d511
Compare
| - Reject malformed, noncanonical, or wiki-qualified input references. | ||
| - Reject a wiki-qualified input even when its qualifier names the current wiki. |
There was a problem hiding this comment.
I don’t think wiki qualification alone should determine whether an input crosses the tenant boundary. currentWiki:Space.Doc still resolves inside the endpoint’s current-wiki scope. We should accept it after verifying that the wiki component equals the actual current wiki and reject only references naming another wiki. This retains canonical local responses and the cross-wiki security boundary without forcing clients to strip an otherwise valid current-wiki qualifier.
There was a problem hiding this comment.
You are right that currentWiki:Space.Doc does not itself cross the tenant boundary. Its rejection is nevertheless intentional, but for canonicalization and disclosure: the request already defines the wiki scope, and current-wiki endpoints accept one wire representation so clients do not depend on a deployment-specific wiki identifier.
I updated the ADR in c4a09ad to make that distinction explicit. CELDEV-1334 and the linked implementation in celements/celements-base#309 specify and test rejection of every qualified reference. If we want both local and same-wiki-qualified inputs accepted, we should reopen that coordinated contract rather than change this ADR alone.
|
|
||
| - Reject malformed, noncanonical, or wiki-qualified input references. | ||
| - Reject a wiki-qualified input even when its qualifier names the current wiki. | ||
| - Serialize response references canonically and locally. |
There was a problem hiding this comment.
I also question the decision to serialize responses locally. Returning Space.Doc loses the reference’s wiki identity: if that value crosses into a request handled by another wiki, it can silently resolve as a different document. Returning the canonical qualified reference (wiki:Space.Doc) preserves provenance and allows the receiving boundary to reject mismatched wiki qualifiers. Combined with accepting qualified input only when its qualifier matches the actual current wiki, this also gives us a safe round-trip contract: the API accepts its own output.
There was a problem hiding this comment.
The local reference is intentionally contextual to the wiki serving the response, just like the relative url; it is not a globally transferable identifier. Within that scope the API already accepts its own output.
I replaced the ambiguous "portable" wording in c4a09ad with the explicit consequence that clients moving a reference between request contexts must retain source-wiki context separately. Returning wiki:Space.Doc would expose a deployment-specific wiki identifier and reverse the local-reference contract in CELDEV-1334 and celements/celements-base#309. A real cross-wiki handoff needs a separate tenant-identity, authorization, and disclosure contract.
| ## Consequences | ||
|
|
||
| - Current-wiki endpoints have an unambiguous tenant boundary. | ||
| - Clients cannot use a current-wiki endpoint as a cross-wiki discovery | ||
| mechanism. | ||
| - Request validation must distinguish canonical local references from malformed, | ||
| noncanonical, and wiki-qualified input. | ||
| - Responses remain portable because their references do not depend on the | ||
| current wiki name. | ||
| - Cross-wiki use cases require deliberate API design rather than an implicit | ||
| extension of a local endpoint. |
There was a problem hiding this comment.
the consequences section largely repeats the decision as outcomes.
There was a problem hiding this comment.
Agreed. I rewrote the section in c4a09ad around the actual trade-offs: callers with qualified current-wiki references must normalize them, response references require request-wiki context, payloads do not expose or depend on internal wiki names, validators can reject qualifiers uniformly, and cross-wiki use requires a separate contract.
There was a problem hiding this comment.
The repeated rationale obscures the ADR’s core decision.
Same points repeat:
- Internal/deployment-specific wiki names: Context and Consequences.
- Contextual/non-portable references: Context, Decision, and Consequences.
- Separate cross-wiki contract: three times.
- Uniform qualifier rejection: Decision and Consequences.
I’d prefer a concise ADR without repetitive wording.
| - Clients holding qualified references, including references qualified with the | ||
| current wiki, must serialize them locally before calling these endpoints. |
There was a problem hiding this comment.
otherWiki:Space.Doc must not be normalized to local Space.Doc
| ## Consequences | ||
|
|
||
| - Current-wiki endpoints have an unambiguous tenant boundary. | ||
| - Clients cannot use a current-wiki endpoint as a cross-wiki discovery | ||
| mechanism. | ||
| - Request validation must distinguish canonical local references from malformed, | ||
| noncanonical, and wiki-qualified input. | ||
| - Responses remain portable because their references do not depend on the | ||
| current wiki name. | ||
| - Cross-wiki use cases require deliberate API design rather than an implicit | ||
| extension of a local endpoint. |
There was a problem hiding this comment.
The repeated rationale obscures the ADR’s core decision.
Same points repeat:
- Internal/deployment-specific wiki names: Context and Consequences.
- Contextual/non-portable references: Context, Decision, and Consequences.
- Separate cross-wiki contract: three times.
- Uniform qualifier rejection: Decision and Consequences.
I’d prefer a concise ADR without repetitive wording.
2 participants
https://synjira.atlassian.net/browse/CELDEV-1334
Summary
Coordinated delivery
Draft 1 of 4 for CELDEV-1334:
Validation
NAVIGATION_API_PLAN.md