Discovery endpoint which resolves an identifier into one or more product release UUIDs.

Exactly one of the tei and purl query parameters shall be provided. A request with neither, or with both, is rejected with 400. OpenAPI cannot express this constraint on query parameters, so both are declared optional here.

Discovery by TEI resolves the product across TEA servers, using the domain carried by the TEI (typically after DNS / .well-known selection of an API host). Discovery by PURL requires an already-known API base URL and resolves within that server's inventory.

A successful response is a non-empty JSON array of discovery-info objects, ordered by priority when multiple product releases match (first entry highest). If the server does not resolve the identifier, it responds with 404 and error: OBJECT_UNKNOWN, not 200 with an empty array.

Parameter values are the identifier itself (not a pre-encoded wire form). Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step. Escapes that are part of a PURL value are preserved by that single decode.

Example request lines after serialization:

• .../discovery?tei=tei%3A%2F%2Fproducts.example.com%2Fuuid%2F47f51950-b0e2-11f1-adc2-1a52914d44b2
• .../discovery?purl=pkg%3Amaven%2Forg.apache.logging.log4j%2Flog4j-core%402.24.3

Unlike /token, this operation is required on a conforming TEA API base for the advertised version. A conforming 404 uses the shared object-not-found response (error-response, typically OBJECT_UNKNOWN) and means this server does not resolve the identifier, not that /discovery is optional or unimplemented. Client recognition of that body and the terminal outcome are defined in the discovery document.

[
  {
    "servers": [
      {
        "rootUrl": "https://api.example.com",
        "versions": [
          "1.0.0"
        ],
        "priority": 0.8
      }
    ]
  }
]