Suggestion: Get any item by ID

[achimwackerow]

I suggest an addition:

Requesting any DDI item by ID could make sense. The DDI ID is assumed to be universally unique. With this assumption, the scope (like variables) doesn't matter.

Formal expression: GET /{itemID}

Anyway, the API looks promising.
Cheers, Achim

[NicoLaval]

Hi @achimwackerow,

Thanks, good idea in principle.

The main constraint is identity: a URN is unambiguous.
A bare id is not always globally unique without agency/version (or explicit disambiguation rules).

So a practical mix is: URN-first lookup for the simple case, plus an optional id path only when you also supply enough context (or we define a strict rule when multiple matches exist).

I’ll refine the exact URL shape on my side, but the contract should stay URN-first, id as convenience with clear rules.

What do you think?

[achimwackerow]

Hi Nicolas,

Absolutely, it only works well with URNs. id works only in the scope of the related DDI agency. This applies for the other cases as well, like GET /variables/{variableID}.

A related document is RFC 9517, A URN Namespace for the Data Documentation Initiative (DDI).

[NicoLaval]

You're absolutely right @achimwackerow , I'll look into consolidating everything, using urns and fallback IDs, and adding the endpoint you described.

Thanks, I'll keep you posted.

[NicoLaval]

Hi @DanSmith,

I had a look to your URL strategy in Colectica, you've chosen the following pattern: item/agency/uuid/version (with optional version).

Why did you do this? Was it motivated by a technical choice? Why not consideritem/agency:uuid:version directly?

Thank you for your insight.

[NicoLaval]

Hi @achimwackerow,

Specification and mock have been updated.

You can now find /ddi/v1/items and /ddi/v1/items/urn endpoint.

Moreover, all endpoints, for items or specific objects, have been rebranded, and require either .../urn (see this example) or .../itemId?agency=...&version=... (see this exemple).

What do you think?

[DanSmith]

Colectica didn't use a DDI URN (colon separated strings) in the item web page paths because the Colectica Repository can handle additional formats besides DDI, it is based on ISO 11179 and the IRDI identification (agency identifier, data identifier, version identifier). The DDI support is actually implemented as an Addin. The separate identification parts are easily handled as route parameters by the framework, and the identity is successively scoped first by agency, then data id, then specific version. The Portal was also created before the DDI URN was available. Also note, the DDI URN requires a urn:ddi: prefix before the identity components.

Using a DDI URN-based route for a DDI-oriented endpoint seems a good choice for DDI Lifecycle and DDI CDI. However, such an endpoint would not support DDI Codebook resources, which was one of the use cases identified by Knut. Perhaps another endpoint type would be needed for DDI Codebook, or require the ddiCodebookUrn actually be available (we don't see these widely used, but they have been available since 2.5).

An identifier-based (rather than item-type-based) resolution endpoint would be valuable when paired with a DDI Registry. DDI object type names are not stable across versions or DDI Lifecycle/DDI CDI products (e.g. SubGroup in DDI 3.2 became Group in DDI 3.3). Relying on type names therefore introduces unnecessary version-specific logic, whereas a pure identifier-driven approach allows the repository to resolve and return the correct item regardless of type differences or changes.

Aside from this single item resolution, in practice the two most useful resolution patterns are:

• Batch retrieval by multiple identifiers in a single request.
• Hierarchical expansion: retrieval of a target DDI item together with its related children (or descendants) to a specified depth (or unbounded).
  For example, fetching a Variable, its associated CodeList, and the underlying Categories as a single payload, rather than requiring dozens of individual requests. This significantly reduces latency and simplifies client-side assembly of complete metadata graphs.

Supporting both flat multi-ID lookup and controlled-depth graph expansion (via query parameters or payload options) would address the predominant real-world usage patterns for DDI resolution.

[NicoLaval]

Hi @DanSmith,

Thank you very much for this detailed and comprehensive response.

We will submit an implementation proposal within the next few days.

Thanks again, Nico