From 3dffca54f0eedfc9e34edcbf0686d5fc1d2a73a0 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Sun, 7 Sep 2025 15:45:39 -0700 Subject: [PATCH] fix(122): always use full resource path for API references The previous guidance was ambiguous about when to use a full resource name vs a relative one. This ambiguity makes it difficult for clients to read the location of the remote resource, as well as the ablity to resolve it as necessary. Some forms of REST APIs already put the full resource name directly in the payload, so there is precedence for this approach. Clarifying the guidance to ensure consistent behavior for APIs. --- aep/general/0122/aep.md.j2 | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/aep/general/0122/aep.md.j2 b/aep/general/0122/aep.md.j2 index 5453c6c5..bd23c33a 100644 --- a/aep/general/0122/aep.md.j2 +++ b/aep/general/0122/aep.md.j2 @@ -147,24 +147,17 @@ all data returned from the API **must** use the canonical resource path. ### Full resource paths -In most cases, resource paths are used within a single API only, or else they -are used in contexts where the owning API is clear (for example, -`string pubsub_topic`). - -However, sometimes it is necessary for services to refer to resources in an -arbitrary API. In this situation, the service **should** use the _full resource -path_, a schemeless URI with the owning API's service endpoint, followed by the -relative resource path: +In most cases, resource paths are used within a single API only. However, +sometimes it is necessary for services to refer to resources in an arbitrary +API. In this situation, the service **must** use the _full resource path_, a +schemeless URI with the owning API's service endpoint, followed by the relative +resource path: ``` //apis.example.com/library/publishers/123/books/les-miserables //apis.example.com/calendar/users/vhugo1802 ``` -**Note:** The full resource path **should not** be used for cross-API -references where the owning API is clear; it is only used if a field refers to -resources in multiple APIs where ambiguity is possible. - ### Resource URIs The full resource path is a schemeless URI, but slightly distinct from the full