Provide API endpoints

Providing API endpoints is an addition to the default IDS interaction that allows to exchange API endpoints. This allows for existing HTTP services to work over IDS. For this the OpenAPI Data App is used.

The process of providing an API is as follows:

1. configure/deploy the backend service implementing an OpenAPI specification,
2. publish the metadata of the service to the metadata broker,
3. perform (automatic) policy negotiation on receival of contract requests,
4. forward the request to the backend service,
5. exchange the response to the request to the requestor.

The test connector deployed at https://test-connector.playground.dataspac.es/ui/ can be used as consumer for the artifact that is deployed on your connector.

Configuration

• Download templates
  • values.public.yaml: https://tno-tsg.gitlab.io/assets/playground/values.public.yaml
• Create IDS Identity secret
  Create an Kubernetes secret containing the certificates that you’ve created in the Request Playground Identities step.

  kubectl create secret generic ids-identity-secret --from-file=ids.crt=./component.crt --from-file=ids.key=./component.key --from-file=ca.crt=./cachain.crt
  

  • Modify ids.info.idsid, ids.info.curator, ids.info.maintainer in the values.local.yaml file to the corresponding identifiers that you filled in during creation of the certificates. ids.info.idsid should be the Connector ID, and ids.info.curator, ids.info.maintainer should be the Participant ID.
• Change Admin User credentials
  The default password is playground but this can be changed to a more secure password, which is especially needed for public Kubernetes deployments.
  • Modify security.users[0].password to a new BCrypt encoded password (e.g. via https://bcrypt-generator.com/)
• Make the connector accessible for others
  To make the connector available for other connectors Ingresses are used.
  • Modify host to the domain name you configured with the ingress controller
  • (Optionally) Set useNewIngress to false in case you’re using an older version of Kubernetes (<=v1.21)
  • (Optionally) Modify coreContainer.ingress.clusterIssuer, coreContainer.ingress.secretName, and/or coreContainer.ingress.annotations to change the behaviour of the main Ingress
  • (Optionally) Modify adminUi.ingress.clusterIssuer, adminUi.ingress.secretName, and/or adminUi.ingress.annotations to change the behaviour of the admin UI Ingress

Deployment

For this the Helm repository must be added:

helm repo add tsg https://nexus.dataspac.es/repository/tsg-helm
helm repo update

After that the Helm chart must be installed, for the public Kubernetes version:

helm upgrade --install playground tsg/tsg-connector --version 3.0.0-master -f values.public.yaml

The user interface of the TSG Core Container will be available at the hostname you’ve configured, on the path /ui/ (e.g. https://domain.name/ui/)

To view the deployment and show the logs of the TSG Core Container, either Lens or kubectl can be used. For Lens, the main view will be Workloads > Pods. For kubectl the following commands can be used to view information of the deployment:

kubectl get pods
kubectl logs -f deployment/playground-tsg-connector-core-container

Providing an API

To provide an API that can be open to other connectors via the OpenAPI data app, you need an OpenAPI specification. This specification needs to be hosted so that the consumer OpenAPI data app can view the specification at all times. Our recommendation for hosting your OpenAPI specification is Swaggerhub.

The first thing we are going to have to change is creating a route in our connector for the OpenAPI data app. This can be done by copying the following snippet in the ids block of the yaml file:

  routes:
    ingress:
      http:
        - endpoint: router
          dataApp: http://-openapi-data-app-http:8080/router
          parameters: "&matchOnUriPrefix=true"

Copy the following code snippet to the bottom of the values.public.yaml file, and make changes where they are requested:

containers:
  - type: data-app
    name: openapi-data-app
    image: docker.nexus.dataspac.es/data-apps/openapi-data-app:feature-infomodel-4.2.7
    apiKey: APIKEY-4DVuWn93ijEo5ZucLgiR # CHANGE
    config:
      openApi:
        usePolicyEnforcement: false
        openApiBaseUrl: <Your openapi spec>
        versions:
          - 0.1.0
        agents:
          - id: <connector ID>:AgentA
            title: <connector name> Agent A
            backEndUrlMapping:
              0.1.0: http://{{ template "tsg-connector.fullname" . }}-<your-api-name>-<service-name>
  - type: helper
    name: <your-api-name>
    image: <your image>
    services:
    - port: 80
      name: <service-name>

As before, change the API key to the previously set API key in values.public.yaml. Fill in the location of the OpenAPI specification in the openApiBaseUrl field. You can specify a version, which is 0.1.0 by default. To create an agent, create an agent ID. We recommend to use the connector ID with an agent ID suffix for this tutorial. The backEndUrlMapping can be done via the Pod name + the service name of the helper, preceded by http://.

More details on the configuration of the OpenAPI data app can be found on Gitlab

Clean-up

If you do not want to proceed with other tutorials, you can remove the resources used.

To remove all of the used Kubernetes resources execute:

helm uninstall playground
kubectl delete secret/ids-identity-secret