Abstract

The EDC Connector is a framework for a sovereign, inter-organizational data exchange. It provides low-level primitives to allow network participants to expose and consume offers. The Connector does so by providing an extensive HTTP API documented via OpenAPI specification.

This project aims to increase the level of abstraction, bringing the low-level HTTP API to mid-level developers by providing an HTTP Client which is thoroughly tested and fully type-safe.

Similarly to the EDC Connector, this library is at its early stage. It aims to maintain compatibility with the latest version of the Connector. API specification can be found on SwaggerHub

Compatibility matrix

|Client |EDC | |--------|-------| |0.4.x |0.6.x | |0.3.0 |0.5.0 | |0.2.1 |0.4.1 | |0.2.0 |0.2.0 |

Usage

Install via npm or yarn

npm install @think-it-labs/edc-connector-client

yarn add @think-it-labs/edc-connector-client

Once installed, clients can be instanciated by construcing a EdcConnectorClient.

With internal context

The standard way of using the client would be associating it with a connector, for doing that it can be instantiated through the EdcConnectorClient.Builder

import { EdcConnectorClient } from "@think-it-labs/edc-connector-client"

const client = new EdcConnectorClient.Builder()
  .apiToken("123456")
  .managementUrl("https://edc.think-it.io/management")
  .publicUrl("https://edc.think-it.io/public")
  .build();

At this point the calls can be made against the specified connector:

const result = await client.management.assets.create({
  properties: {
      "name": "asset name",
      "key": "any value"
  },
  dataAddress: {
    name: "An HTTP address",
    baseUrl: "https://example.com/",
    type: "HttpData",
    path: "/some-data",
    contentType: "application/json",
    method: "GET",
  },
});

Without internal context

A single connector instance can be used to call multiple connectors, just creating different contexts and passing them to the specific call.

The connector can be instantiated directly without the builder:

import { EdcConnectorClient } from "@think-it-labs/edc-connector-client"

const client = new EdcConnectorClient();

Context objects can be created with a createContext call:

const context = client.createContext("123456", {
  default: "https://edc.think-it.io/api",
  management: "https://edc.think-it.io/management",
  protocol: "https://edc.think-it.io/protocol",
  public: "https://edc.think-it.io/public",
  control: "https://edc.think-it.io/control",
});

And the context can be passed to every call as latest argument:

const result = await client.management.assets.create(context, {
  asset: {
    properties: {
      "name": "asset name",
      "key": "any value"
    },
    dataAddress: {
      name: "An HTTP address",
      baseUrl: "https://example.com/",
      type: "HttpData",
      path: "/some-data",
      contentType: "application/json",
      method: "GET",
    },
  }
});

Error handling

All API methods are type, and error-safe, which means arguments are fully typed with TypeScript, and thrown errors are always EdcConnectorClientError instances. This error safety level is achieved using the TypedError library.

import { EdcConnectorClientError, EdcConnectorClientErrorType } from "@think-it-labs/edc-connector-client"

try {

  // perform async EdcConnectorClient actions

} catch(error) {
  if (error instanceof EdcConnectorClientError) {
    switch (error.type) {
      case EdcConnectorClientErrorType.Duplicate: {
        // handle duplicate error
      }

      // ...

      case EdcConnectorClientErrorType.Unknown:
      default: {
        // red alert: unknown behaviour
      }
    }
  }
}

Note if you encounter an Unknown error you should report this behavior along steps to reproduce it. Unknown behaviors are unwanted and must be fixed asap.

Development

docker compose is used to run the development environment. It runs two connectors with capabilities described in the gradle configuration file.

Please, adhere to the CONTRIBUTING guidelines when suggesting changes in this repository.

Release

The release github action workflow takes care of release.

License

Copyright 2022-2023 Think.iT GmbH.

Licensed under the Apache License, Version 2.0. Files in the project may not be copied, modified, or distributed except according to those terms.