Using Basic Discovery#

This walkthrough uses the unsecured, standalone Compose setup at http://localhost:8086, with an empty context path. Save the JSON files in your working directory and run the commands in order against an example database. In Windows PowerShell, use curl.exe instead of curl. Include any configured context path in each URL.

The requests below demonstrate standalone Discovery replacement and deletion. DTR changes the asset-link POST to append semantics and requires an existing descriptor; compare Differences from Standalone Registry and Discovery. If Discovery is integrated with an AAS Registry, also read Registry Integration before changing mappings.

Only the Discovery Service, PostgreSQL, and the Configuration Service are required. A Registry or Repository is needed only when continuing from the discovered identifier to a descriptor or AAS content.

Find an AAS by an Asset Identifier#

Save this as lookup.json:

[
  { "name": "serialNumber", "value": "SN-001" }
]
curl -i -X POST 'http://localhost:8086/lookup/shellsByAssetLink?limit=10' -H 'Content-Type: application/json' --data-binary '@lookup.json'

Expect 200 OK. In a database containing only this example, the response is:

{
  "paging_metadata": {},
  "result": ["urn:example:aas:1"]
}

The returned AAS identifier is unencoded. Encode it before using it in a Registry or Repository URL. If the corresponding descriptor has also been registered, follow the AAS Registry usage guide to retrieve it. A separate Registry setup and descriptor registration are required; Discovery registration alone does not create the descriptor.

Global Asset Identifier Lookup#

Replace the contents of lookup.json with:

[
  { "name": "globalAssetId", "value": "urn:example:asset:1" }
]

Repeat the POST lookup request. Expect the same AAS identifier. To require both the global asset identifier and serial number, send both objects in the lookup array. All supplied links must match; adding an unmatched link produces no match for this AAS.

Pagination#

The limit and cursor parameters apply to the POST lookup endpoint. For additional pages, submit the same lookup body with the returned cursor:

curl -i -X POST 'http://localhost:8086/lookup/shellsByAssetLink?limit=10&cursor=RETURNED_CURSOR' -H 'Content-Type: application/json' --data-binary '@lookup.json'

Replace RETURNED_CURSOR with the server-provided value, URL-escaped as needed. The single registration above has no next page. See Follow the Next Cursor for the shared continuation rules. An unmatched lookup returns 200 OK with an empty result; it does not return 404.

Deprecated GET Lookup#

For existing clients, GET /lookup/shells accepts assetIds query parameters containing Base64URL-encoded JSON asset links. Valid padded and unpadded values are accepted; the example uses the unpadded form. The preferred POST endpoint avoids this additional encoding step. For the original serial-number lookup:

curl -i -G http://localhost:8086/lookup/shells --data-urlencode 'assetIds=eyJuYW1lIjoic2VyaWFsTnVtYmVyIiwidmFsdWUiOiJTTi0wMDEifQ'

The encoded value represents {"name":"serialNumber","value":"SN-001"}. Expect the same paged AAS identifier response as the POST lookup.

Delete the Discovery Registration#

Warning

In a Registry-integrated deployment, deleting the Discovery registration can also remove linked specificAssetIds from the corresponding AAS Descriptor. It does not delete the descriptor or any Repository AAS/Submodel content. See Registry Integration.

curl -i -X DELETE http://localhost:8086/lookup/shells/dXJuOmV4YW1wbGU6YWFzOjE
curl -i http://localhost:8086/lookup/shells/dXJuOmV4YW1wbGU6YWFzOjE

Expect 204 No Content for deletion and 404 Not Found for the subsequent read. Repeating an asset-link lookup returns an empty result for this example. The AAS content in a Repository is unaffected.