Skip to content

translationBridge IDD

generic_http & generic_https

Overview

This page describes the generic_http and generic_https service interface of translationBridge, which enables to find providers whose service operation is accessible by the requester via a translation bridge using the currently available translators. The service also allows to build or abort such bridges. To enable other systems to use, to consume it, this service needs to be offered through the ServiceRegistry.

Hereby the Interface Design Description (IDD) is provided to the translationBridge – Service Description. For further details about how this service is meant to be used, please consult that document.

Interface Description

discovery

The service operation request requires an identity related header or certificate and a TranslationDiscoveryRequest JSON encoded body.

POST /translation/bridge/discovery HTTP/1.1
Authorization: Bearer <authorization-info>

{
  "candidates": [
    {
      "instanceId": "DoubleProvider|doubleService|1.0.0",
      "provider": {
        "name": "DoubleProvider"
      },
      "serviceDefinition": {
        "name": "doubleService"
      },
      "interfaces": [
        {
          "templateName": "generic_http",
          "policy": "USAGE_LIMITED_TOKEN_AUTH",
          "properties": {
            "accessAddresses": [
              "127.0.0.1"
            ],
            "accessPort": 23456,
            "operations": {
              "make-double": {
                "path": "/make-double",
                "method": "POST"
              }
            },
            "basePath": "/double",
            "dataModels": {
              "make-double": {
                "input": "testXml01",
                "output": "testXml01"
              }
            }
          }
        }
      ]
    }
  ],
  "operation": "make-double",
  "interfaceTemplateNames": [
    "generic_http"
  ],
  "inputDataModelId": "testJson01",
  "outputDataModelId": "testJson01"
}

Note: The service operation can only work on candidates with interfaces that describe their data models. Data models must be described as a DataModelMap inside the interface properties. See the example above.

The service operation responds with the status code 200 and with a TranslationDiscoveryResponse JSON encoded body.

{
  "bridgeId": "2240efa3-fde4-4f81-a625-04f1234acee7",
  "candidates": [
    {
      "serviceInstanceId": "DoubleProvider|doubleService|1.0.0",
      "interfaceTemplateName": "generic_http"
    }
  ]
}

The error codes are 400 if the request is malformed, 401 if the requester authentication was unsuccessful, 403 if the authenticated requester has no permission, 500 if an unexpected internal error happens and 503 if an unexpected error happens while communicating with other systems. The error response also contains an ErrorResponse JSON encoded body.

{
  "errorMessage": "operation is missing",
  "errorCode": 400,
  "exceptionType": "INVALID_PARAMETER",
  "origin": "POST  /translation/bridge/discovery"
}

negotiation

The service operation request requires an identity related header or certificate and a TranslationNegotiationRequest JSON encoded body.

Operation negotiation can be used two ways.

  • A. Using the results of a previously executed discovery by specifing a valid bridgeId.
  • B. Creating the discovery results during the negotiation by not specifing a valid bridgeId. This case requires additional information about the translation task in the request.

Example request for case A

POST /translation/bridge/negotiation HTTP/1.1
Authorization: Bearer <authorization-info>

{
  "bridgeId": "2240efa3-fde4-4f81-a625-04f1234acee7",
  "target": {
    "instanceId": "DoubleProvider|doubleService|1.0.0"
  }
}

Example request for case B

POST /translation/bridge/negotiation HTTP/1.1
Authorization: Bearer <authorization-info>

{
  "target": {
    "instanceId": "DoubleProvider|doubleService|1.0.0",
    "provider": {
      "name": "DoubleProvider"

    },
    "serviceDefinition": {
      "name": "doubleService"
    },
    "interfaces": [
      {
        "templateName": "generic_http",
        "policy": "USAGE_LIMITED_TOKEN_AUTH",
        "properties": {
          "accessAddresses": [
            "127.0.0.1"
          ],
          "accessPort": 23456,
          "operations": {
            "make-double": {
              "path": "/make-double",
              "method": "POST"
            }
          },
          "basePath": "/double",
          "dataModels": {
            "make-double": {
              "input": "testXml01",
              "output": "testXml01"
            }
          }
        }
      }
    ]
  },
  "operation": "make-double",
  "interfaceTemplateName": "generic_http",
  "inputDataModelId": "testJson01",
  "outputDataModelId": "testJson01"
}

The service operation responds with the status code 201 if called successfully and with a TranslationNegotiationResponse JSON encoded body.

{
  "bridgeId": "2240efa3-fde4-4f81-a625-04f1234acee7",
  "bridgeInterface": {
    "templateName": "generic_http",
    "protocol": "http",
    "policy": "TRANSLATION_BRIDGE_TOKEN_AUTH",
    "properties": {
      "dataModels": {
        "make-double": {
          "input": "testJson01",
          "output": "testJson01"
        }
      },
      "operations": {
        "make-double": {
          "path": "/83a22bd8-d189-4c50-ba1a-ff5b32a2e3ca",
          "method": "POST"
        }
      },
      "basePath": "/interface/translator/dynamic",
      "accessAddresses": [
        "127.0.0.1"
      ],
      "accessPort": 12501
    }
  },
  "tokenUsageLimit": 5
}

The error codes are 400 if the request is malformed, 401 if the requester authentication was unsuccessful, 403 if the authenticated requester has no permission, 500 if an unexpected internal error happens and 503 if an unexpected error happens while communicating with other systems. The error response also contains an ErrorResponse JSON encoded body.

{
  "errorMessage": "Service instance id is missing",
  "errorCode": 400,
  "exceptionType": "INVALID_PARAMETER",
  "origin": "POST  /translation/bridge/negotiation"
}

abort

The service operation request requires an identity related header or certificate and a TranslationBridgeID as path parameter, which is a unique identifier of the translation bridge to be aborted.

DELETE /translation/bridge/abort/2240efa3-fde4-4f81-a625-04f1234acee7 HTTP/1.1
Authorization: Bearer <authorization-info>

The service operation responds with the status code 200 if called successfully and an existing translation bridge was aborted and 204 if no translation bridge was found. The success response does not contain any response body.

The error codes are 400 if the request is malformed, 401 if the requester authentication was unsuccessful, 403 if the authenticated requester has no permission, 500 if an unexpected internal error happens and 503 if an unexpected error happens while communicating with other systems. The error response also contains an ErrorResponse JSON encoded body.

{
  "errorMessage": "No permission to abort bridge: 2240efa3-fde4-4f81-a625-04f1234acee7",
  "errorCode": 403,
  "exceptionType": "FORBIDDEN",
  "origin": "DELETE  /translation/bridge/abort/2240efa3-fde4-4f81-a625-04f1234acee7"
}