# Company Lookup

![GitHub](https://img.shields.io/github/license/eclipse-basyx/basyx-go-components)

## Contents

* [Creating your own Set-Up](setup)

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:

```json
{
  "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`:

```http
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/`:

```http
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:

- [General Configuration](../common/configuration)
- [Swagger UI Docs](../common/swagger)
- [Common / Shared Features](../common/shared_features)

```{toctree}
:hidden:
:maxdepth: 1

setup
```