Company Lookup

Company Lookup#

GitHub

Contents#

The BaSyx Company Lookup is a component for discovering company-provided service endpoints in dataspaces, for example AAS registries, repositories, discovery services, AASX file servers, MQTT brokers, and EDC protocol endpoints.

Companies are represented by Company Descriptors. Clients can retrieve a descriptor by its company domain or search descriptors by company name and asset ID.

Company Descriptor#

A Company Descriptor uses common AAS Descriptor properties and adds company-specific discovery information.

JSON attribute

Explanation

Type

Card.

administration

Administrative information

AdministrativeInformation

0..1

description

Multilingual description

LangStringTextType

0..*

displayName

Multilingual display name

LangStringNameType

0..*

endpoints

Endpoints of company-provided network resources

Endpoint

1..*

idShort

Short name of the company descriptor

NameType

0..1

domain

Company domain and unique descriptor identifier

String

1

name

Company name

String

1

nameOptions

Alternative company names

String

0..*

assetIdRegexPatterns

Regular expressions for asset IDs associated with the company

String

0..*

The domain must be a syntactically valid domain containing at least two labels. It is unique within the Company Lookup.

Every endpoint requires interface and protocolInformation. Supported endpoint interfaces are:

  • AAS-DISCOVERY-3.0 and AAS-DISCOVERY-3.1

  • AAS-REGISTRY-3.0 and AAS-REGISTRY-3.1

  • AAS-REPOSITORY-3.0 and AAS-REPOSITORY-3.1

  • SUBMODEL-REGISTRY-3.0 and SUBMODEL-REGISTRY-3.1

  • SUBMODEL-REPOSITORY-3.0 and SUBMODEL-REPOSITORY-3.1

  • AASX-FILE-3.0 and AASX-FILE-3.1

  • MQTT-BROKER-3.1.1

  • EDC-PROTOCOL

A descriptor must contain at least one of the AAS, Submodel, or AASX interfaces listed above. MQTT-BROKER-3.1.1 and EDC-PROTOCOL may be added, but neither satisfies this requirement by itself.

API Endpoints#

The Company Lookup provides these main API endpoints:

  • GET /companies: Returns a paged list of Company Descriptors. It supports the optional query parameters

    • name to filter the results based on the company name and

    • assetId to filter the results based on an asset ID.

  • GET /companies/{companyIdentifier}: Returns the descriptor identified by its company domain.

  • POST /companies: Creates a Company Descriptor.

  • PUT /companies/{companyIdentifier}: Replaces an existing Company Descriptor.

  • DELETE /companies/{companyIdentifier}: Deletes a Company Descriptor.

POST returns 201 Created. PUT and successful GET requests return 200 OK. DELETE returns 204 No Content. Invalid input returns 400 Bad Request, duplicate creation returns 409 Conflict, and requests for nonexistent descriptors return 404 Not Found.

For PUT, the body domain must match the domain encoded in the path, and the descriptor must already exist.

Encoding#

The following values must be base64url encoded:

  • the companyIdentifier path parameter;

  • the name query parameter;

  • the assetId query parameter.

The encoding uses UTF-8 and URL-safe Base64 without padding. For example, iese.fraunhofer.de is encoded as aWVzZS5mcmF1bmhvZmVyLmRl.

The limit parameter is a regular integer and is not encoded. A paging cursor is generated by the server in encoded form and must be passed back unchanged.

Listing and Pagination#

GET /companies accepts these optional query parameters:

  • limit: Maximum number of returned descriptors; it must be at least 1. The default is 100.

  • cursor: Value returned in paging_metadata.cursor by the preceding request.

  • name: Base64url-encoded company name.

  • assetId: Base64url-encoded asset ID.

The response is a paged result:

{
  "paging_metadata": {
    "cursor": "ZXhhbXBsZS5jb20"
  },
  "result": []
}

The cursor property is omitted when there is no next page.

Filtering by Name#

The name filter performs an exact, case-insensitive match against name and every entry in nameOptions.

For example, Fraunhofer IESE is encoded as RnJhdW5ob2ZlciBJRVNF:

GET /companies?name=RnJhdW5ob2ZlciBJRVNF

Filtering by Asset ID#

The assetId filter returns descriptors for which the decoded asset ID matches at least one regular expression in assetIdRegexPatterns. Regular-expression matching is case-sensitive.

For example, the asset ID https://i.iese.fraunhofer.de/assetId/assets/4711 is encoded as aHR0cHM6Ly9pLmllc2UuZnJhdW5ob2Zlci5kZS9hc3NldElkL2Fzc2V0cy80NzEx and matches the asset ID regular expression pattern ^https://i\\.iese\\.fraunhofer\\.de/assetId/:

GET /companies?assetId=aHR0cHM6Ly9pLmllc2UuZnJhdW5ob2Zlci5kZS9hc3NldElkL2Fzc2V0cy80NzEx

The name and assetId filters can be combined; a descriptor must then satisfy both filters.

Common Documentation#

Company Lookup uses the shared BaSyx Go infrastructure for configuration, Swagger/OpenAPI, and CORS. Shared documentation is available here: