API Use ¶

The Rosetta Ingest Component and Rosetta Features such as Validation and Reports can be accessed directly via a RESTful service which is automatically deployed to the cloud on demand. As the Application allows a model to be modified, when an API is exported, it provides a snapshot of the service with the state of the model at the time of export. As a model is further developed, the API can be re-exported on demand.

In this section, you will learn about:

• Available Rosetta services
• Rosetta services details
• Hosted API overview
• On premise API overview

Available Rosetta Services ¶

The APIs available in Rosetta are:

• JSON Validator Service
• Run Function Service
• Regulation Report Service
• Ingestion Service

Other services, such as Projection Service, will be added to this list.

Rosetta Services Details ¶

JSON Validator Service ¶

The model defines cardinality and data rules which can be used to validate the model data. The JSON Validator Service will list all of the diagnostic errors found.

The service uses the below URL with {{owner-name}} and {{workspace-name}} defined in the Exporting the service section.

1

https://ui.rosetta-technology.io/api/promoted/validation/{{owner-name}}/{{workspace-name}}/{{rosetta-object-type}}

JSON Validator Parameters ¶

The result of the API will be a JSON array that follows the structure:

1
2
3
4
5
6
7
8
9

[
  {
    "name": "Rule name",
    "modelObjectName": "Model type that failed validation",
    "reason": "The reason of failure",
    "type": "One of the following types of failures: DATA_RULE, CHOICE_RULE, MODEL_INSTANCE, ONLY_EXISTS, POST_PROCESS_EXCEPTION",
    "path": "Path of the type that follows the json object being validated"
  }
]

The example of the output could look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

[
  {
    "name": "ContractContractualProductExists",
    "modelObjectName": "Contract",
    "reason": "[Contract->getTradableProduct] does not exist",
    "type": "DATA_RULE",
    "path": "Contract"
  },
  {
    "name": "Contract",
    "modelObjectName": "ContractBuilder",
    "reason": "tradeDate - Expected cardinality lower bound of [1] found [0]; tradableProduct - Expected cardinality lower bound of [1] found [0]",
    "type": "MODEL_INSTANCE",
    "path": "Contract"
  },
  {
    "name": "IdentifierIssuerChoice",
    "modelObjectName": "Identifier",
    "reason": "One and only one field must be set of 'issuerReference', 'issuer'. No fields are set.",
    "type": "CHOICE_RULE",
    "path": "Contract.contractIdentifier(0)"
  }
]

Run Function Service ¶

This service exports a REST API that runs the specified Rosetta function with the given input JSON data.

The service uses the below URL with {{owner-name}} and {{workspace-name}} defined in the Exporting the service section.

1

https://ui.rosetta-technology.io/api/promoted/run-function/{{owner-name}}/{{workspace-name}}/{{rosetta-function-type}}

Run Function Parameters ¶

The input JSON data should match the arguments of the function. For example, given the following Rosetta function

1
2
3
4
5
6
7

func Add: <"Returns the sum of the two numbers provided.">
  inputs:
    a number (1..1)
    b number (1..1)
  output:
    result number (1..1)
  set result: a + b

Input JSON example:

1
2
3
4

{
  "a": 1,
  "b": 2
}

Result JSON example:

1
2
3

{
  "result": 3
}

Regulation Report Service ¶

This service exports a REST API that produces a regulatory report given a JSON model instances.

The service uses the below URL with {{owner-name}} and {{workspace-name}} defined in the Exporting the service section.

1

https://ui.rosetta-technology.io/api/promoted/report/{{owner-name}}/{{workspace-name}}/{{namespace}}/{{regulatory-body}}/{{regulatory-corpus-list}}

Regulation Report Parameters ¶

For a report defined as report EuropeanParliament EmissionPerformanceStandardsEU, the url will end with /EuropeanParliament/EmissionPerformanceStandardsEU.

The result of the API will be a JSON object that follows the structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "identifier": "demo.emissions.<EuropeanParliament EmissionPerformanceStandardsEU>",
  "results": [
    {
      "sampleName": "Exported sample",
      "report": { <Rosetta report object, for example, `EuropeanParliamentReport` in the Demonstration Model>
        "vehicleRegistrationID" : "X1",
        "firstRegistrationDate" : "2020-01-01",
        "vehicleClassificationType" : "M1_Passengers",
        "engineType" : "Petrol",
        "euroEmissionStandard" : "Euro 5 Standard",
        "carbonMonoxide" : 0
      }
    }
  ]
}

Ingestion Service ¶

The model defines synonyms which map external data models to types defined in a model expressed in Rosetta. Once the synonyms are in place, executable mapping code is generated and can be exposed using a REST API.

The service uses the below URL with {{owner-name}} and {{workspace-name}} defined in the Exporting the service section.

1

https://ui.rosetta-technology.io/api/promoted/ingest/{{owner-name}}/{{workspace-name}}/latest/{{ingestion-environment-name}}

The content type header must be set to application/xml if ingesting an XML document, such as example 1 for Example 1.1 of Conditional Default basic mapping available in the Demonstration Model.

Ingest Parameters ¶

The result of the API will be a JSON array that follows the structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

{
  "rosettaModelInstance": {
    "engineSpecification": {
      "capacityUnit": "Gallon",
      "fuelType": "Petrol"
    }
  },
  "inputValidation": {},
  "mappingReport": {
    "mappingResults": [
      {
        "success": true,
        "externalPath": {
          "parent": {
            "parent": {
              "parent": {
                "element": {
                  "uri": "CONDITIONAL_DEFAULT_EXAMPLE_1",
                  "path": "engine"
                }
              },
              "element": {
                "uri": "CONDITIONAL_DEFAULT_EXAMPLE_1",
                "path": "engineType"
              }
            },
            "element": {
              "uri": "CONDITIONAL_DEFAULT_EXAMPLE_1",
              "path": "engineDetail"
            }
          },
          "element": {
            "uri": "CONDITIONAL_DEFAULT_EXAMPLE_1",
            "path": "volumeCapacityUnit"
          }
        },
        "value": "Gallon",
        "internalPaths": {
          "Root.engineSpecification.capacityUnit": [
            "Gallon"
          ]
        },
        "result": "Success",
        "excludedExternalPath": false,
        "condition": false,
        "externalPathString": "engine.engineType.engineDetail.volumeCapacityUnit",
        "externalPathNoMeta": "engine.engineType.engineDetail.volumeCapacityUnit"
      },
    ],
    "successCount": 2,
    "completeness": 66.66666666666666,
    "success": false,
    "externalPaths": 3,
    ],
  },
  "validationReport": {
    "validationResults": [
      {
        "modelObjectName": "BuilderProxy",
        "name": "Root",
        "validationType": "MODEL_INSTANCE",
        "path": {
          "element": {
            "uri": "CONDITIONAL_DEFAULT_EXAMPLE_1",
            "path": "Root"
          }
        },
        "success": true

Hosted API Overview ¶

Our hosted API services are available from the API Export menu:

Rate limited service ¶

The API requests are rate limited. The maximum rate of requests are dependent upon the user's license, which indicates a maximum number of requests per second and per month.

When a request is rate limited, the server will respond with a 429 error code. We are using a 'sliding window count' algorithm. This means given a certain time window only a certain number of requests are allowed. The time window will move each second. The rate limit is applied across API calls.

API-KEY ¶

The API must be used in conjunction with an API-KEY for access authorisation. This API-KEY is created at export time and the same API-KEY will be used for all further exports and is unique per user Workspace. The API-KEY is a JWT token. The user's license is encoded within the JWT token. We are not using a Bearer token rather an Authorization key and the JWT token as the value.

Exporting the service ¶

In Rosetta, open API Export by clicking on the link at the bottom banner. The list of supported APIs will be displayed on the left vertical pannel. The Play button will be disabled if the model is being built or in an error state indicated by the status monitor light on the bottom right of the screen.

Select an API to export from the list displayed, and then click the Play button . This will expose a REST endpoint URL which points to the user's workspace model, and an API-KEY which provides authorization.

All exported APIs communicate to the servers over HTTPS using SHA-256 with RSA Encryption.

In general, the API uses HTTP POST requests with JSON or XML arguments and JSON responses. Request authorisation is achieved using the request header Authorization: <API-KEY> and follows the URL pattern:

1

https://ui.rosetta-technology.io/api/promoted/{{service-name}}/{{owner-name}}/{{workspace-name}}/{{service-parameters}}

API Export URL Arguments ¶

All APIs are pre-exported in the Public Workspace and are available to use straight away with a shared API-KEY.

Accessing the service ¶

The services can be accessed using a number of different approaches:

1. Export a service as a REST API and invoke using a REST client e.g. cURL which is distributed with all modern server operating systems.
2. Export a service as a REST API and invoke programmatically using JAVA utility libraries.
3. Upload files into the Rosetta UI (Using the Ingest, Projection and Validation panels).

Examples are provided for cURL and JAVA.

Using cURL ¶

When the API is exported, an example is provided which uses the command line REST client cURL. To get started, an example cURL is provided in the application that will send the JSON/XML data to the exported API. The examples can be copied directly from the API Export panel.

Programmatic Access ¶

The exported API can also be accessed programmatically using JAVA. Developers are free to use any HTTP library.

Use the below maven dependencies to get access to the libraries required to access the exported API from JAVA.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

<dependency>
    <groupId>com.mashape.unirest</groupId>
    <artifactId>unirest-java</artifactId>
    <version>1.4.9</version>
</dependency>

<dependency>
    <groupId>com.regnosys.rosetta</groupId>
    <artifactId>com.regnosys.rosetta.lib</artifactId>
    <version>LATEST</version>
</dependency>

<dependency>
    <groupId>com.regnosys</groupId>
    <artifactId>rosetta-common</artifactId>
    <version>LATEST</version>
</dependency>

See below for a simple example in Java.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

public void callExportedApi() throws JsonProcessingException, UnirestException {
    // Generated by Rosetta Core when API Export is run

    String serviceName = <INSERT SERVICE NAME>;
    String ownerName = <INSERT USER NAME>;
    String workspaceName = <INSERT WORKSPACE NAME>;
    String serviceParameters = <INSERT PARAMETERS>;

    String restEndpointUrl = String.format(
        "https://ui.rosetta-technology.io/api/promoted/%s/%s/%s/%s/%s",
            serviceName,
            ownerName,
            workspaceName,
            serviceParameters);

    String contentType = "application/json";

    String apiKey = <INSERT APK_KEY HERE>;
    String body = <INSERT BODY HERE>;

    // Build request, and POST to REST API
    HttpResponse<String> apiResponse = Unirest.post(restEndpointUrl)
        .header("Authorization", apiKey)
        .header("content-type", contentType)
        .body(body)
        .asString();

    // API response
    String response = apiResponse.getBody();
}

Each service will have a different set of inputs and outputs which are documented below.

On Premise API Overview ¶

Overview ¶

This guide provides instructions concerned with the installation and use of the REGnosys services when deployed on premises. It provides details on the docker configuration, application configuration and application usage.

Available Rosetta Services ¶

The on premise APIs available are:

• Rosetta Ingest
• Rosetta Engine Reports

Common System Requirements ¶

Docker ¶

Rosetta on premises services are distributed as Docker images and can be installed on any number of different platforms that support Docker images. For this guide, a local Docker installation with access to the command line is required by installing the Docker Engine (see https://docs.docker.com/get-docker/). Rosetta on premises services are platform agnostic and will work with any docker installation so long as there is access to a HTTP port. It is recommended to have at least 1GB of memory available to the process.

Credentials ¶

The Docker image registry requires authentication. Please contact your sales representation at REGnosys.

Installation ¶

Docker Image Information ¶

To log in to the REGnosys docker registry, use the below command with the credentials provided:

cat /my/file/path/key.json | docker login -u _json_key --password-stdin \
europe-west1-docker.pkg.dev/production-208613/

Transfer the regnosys/rosetta-{{service}}/{{service-particulars}}:{{image version}} Docker image from the REGnosys docker registry to the local on premise Docker installation by pulling the image:

docker pull europe-west1-docker.pkg.dev/production-208613/{{client-name}}/regnosys/rosetta-{{service}}/{{service-particulars}}:{{image version}}

Application Configuration ¶

The internal container port 9000 must be exposed to access the service by using the -p flag. The internal container ports can be overridden using the below environment variables:

Container Port Environment Variables ¶

Administration Services ¶

The service also contains a ping and a healthcheck rest endpoint designed to check if the service is up and running. These services are available on port 8001 which can optionally be exposed.

Run the Docker Image ¶

The run command:

docker run -it -p 9000:9000 -p 8001:8001 -e APP_PORT=9000 europe-west1-docker.pkg.dev/production-208613/{{client-name}}/regnosys/rosetta-{{service}}/{{service-particulars}}:{{image version}}

The above command will start the service and expose it on port 9000. The health checks will be available at the URL: http://localhost:8001/healthcheck?pretty=true The Ping will be available at the URL: http://localhost:8001/ping

Open API Specification ¶

Rosetta on premises services utilise APIs exposed using the Open API specification and can be seen on a browser using the URL: http://localhost:9000/api/swagger#/ assuming that you are running locally. See the following screen shot as an illustration.

Supported Model Version ¶

To check what Model Version JSON will be produced, use the model version endpoint:

curl -X GET "http://localhost:9000/api/rosetta-{{service}}/{{service-particulars}}/model-version" -H "accept: application/json"

Example response:

{
    "modelVersion": "1.2.3.4"
}

Rosetta Ingest ¶

Rosetta Ingest will translate JSON documents to model documents as defined by the model synonyms source.

• Docker Image Coordinates: regnosys/rosetta-ingest/{{model}}/{{synonym}}

Using the API ¶

To see what synonym sources are supported use the endpoint: http://localhost:9000/api/swagger#/RosettaIngest/supportedSynonyms

The endpoint will contain the schema requirements for each supported synonym source. For example, {{synonym}}, the below will be available:

Schema Requirements ¶

Example request:

curl -X GET "http://localhost:9000/api/ingest/supported-synonyms" -H "accept: application/json"

Example response:

[
    {
    "synonymSourceName": "{{synonym}}",
    "inputType": "application/xml",
    "outputType": "com.legal.info.ASample",
    "mappingCoverages": [
        {
        "ingestionEnvironment": "{{SAMPLE_DATA}}",
        "schema": {
            "document-name": "my-sample-data-2019",
            "env": "production",
            "version": "0.1"
        },
        "mappingCoverage": 1.0
        }
    ]
    }
]

We can see the {{synonym}} is supported which consumes JSON and produces JSON conforming to {{synonym}} type com.legal.info.ASample. In addition, the mapping coverage shows that the supported schema is my-sample-data-2019 in production environment with version 0.1. As more schemas are supported, the list will grow.

Ingest {{synonym}} JSON to Rosetta Object ¶

To transform a {{synonym}} JSON to Rosetta Object use the http://localhost:9000/api/swagger#/RosettaIngest/ingestJson API endpoint:

curl -X POST "http://localhost:9000/api/ingest/{{synonym}}" -H "accept: application/json" -H "Content-Type: application/json" -d @PATH_TO_JSON

A {{synonym}} JSON document will be returned form the API conforming the {{synonym}} type com.legal.info.ASample:

{
    "agreementDate": {
    "day": 1,
    "month": 4,
    "year": 2019
    },
    "agreementType": {
    "governingLaw": "GBEN",
    "name": "CREDIT_SUPPORT_DEED",
    "publisher": "ISDA",
    "vintage": "2016"
    },
    "contractualParty": [
    {
        "value": {
        "meta": {
            "globalKey": "d7a9f0df",
            "externalKey": "partyA"
        },
        "name": {
        "value": "Foo"
        },
        "partyId": [
            {
            "value": "63291ce9-436d-39ad-a731-a6de1d8f4e32"
            }
        ]
        }
    },
    ]
    ...

The API will attempt to translate any document to the {{synonym}} format. You can specify query parameters that will restrict the translation to only supported schemas.

Query Params ¶

Example URL for translating JSON and specifying the document-name, version and env:

http://localhost:9000/api/ingest/{{synonym}}?document-name=my-sample-data-2019&env=production&version=0.1

Ingest {{synonym}} XML to Rosetta Object ¶

To transform a {{synonym}} XML to Rosetta object, use the http://localhost:9000/api/swagger#/RosettaIngest/ingestXml API endpoint:

curl -X POST "http://localhost:9000/api/ingest/{{synonym}} " -H "accept: application/json" -H "Content-Type: application/xml" -d @PATH_TO_XML

This flow works in exactly the same way as the JSON translation flow, except that it accepts XML documents. It is necessary to change the content type to application/xml to activate it.

Rosetta Engine Reports ¶

Rosetta Engine Reports will run preconfigured reports against input model documents.

• Docker image: regnosys/rosetta-engine/reports/{{model}}/{{report-body}}/{{report-corpus*}}/

Using the API ¶

To see the report supported, use the endpoint: http://localhost:9000/api/swagger#/RosettaEngineReports/supportedReport

The endpoint will contain the schema requirements for each supported report. For example, {{report}}, the below will be available:

Schema Requirements ¶

Example request:

curl -X GET "http://localhost:9000/api/engine/reports/supported-report" -H "accept: application/json"

Example response:

{
    "body": "sample-standards-body",
    "corpusList": "corpus1/corpus2",
    "inputModelType": "com.legal.info.ASample",
    "name": "sample-standards-bodycorpus1_corpus2",
    "className": "cdm.regulation.sample-standards-body.corpus1.corpus2.blueprint.sample-standards-bodycorpus1_corpus2Report"}
}

We can see the {{report}} is supported which consumes JSON and produces JSON conforming to {{inputModelType}} type com.legal.info.ASample.

Run {{report}} on a model data document ¶

To run {{report}} on a model data document or array of model data documents, use the http://localhost:9000/api/swagger#/RosettaEngineReports/runReport API endpoint. You can specify as many corpus items as required in the request endpoint path. The API will attempt to generate a report against any document conforming to the Rosetta object format of the {{inputModelType}} type.:

curl -X POST "http://localhost:9000/api/engine/reports/{{body}}/{{corpus1}}/{{corpus2}}" -H "accept: application/json" -H "Content-Type: application/json" -d @PATH_TO_JSON

For example, the input JSON might look as follows:

[
    {
      "action" : "NEW",
      "businessEvent" : {
        "eventDate" : {
          "day" : 1,
          "month" : 2,
          "year" : 2019
        },
        "eventQualifier" : "ContractFormation",
        ...
      ...
    },
    {
      "action" : "NEW",
      "businessEvent" : {
        "eventDate" : {
          "day" : 2,
          "month" : 2,
          "year" : 2019
        },
        "eventQualifier" : "ContractFormation",
        ...
      ...
    }
...

The {{report}} will be output as a JSON document conforming to the following format:

{
    "body": "body",
    "corpus": ["corpus1", "corpus2"],
    "rows": [
        [
            {
                "name": "field name e.g. Report Timestamp",
                "value": "1981-04-13 07:51:20"
            },
             ...
        ],
        ...
    ]
}

The document echos the supported body and corpus at the top-level. The data is issued as a two-dimensional array of key-value pairs. The key-value pair combines the column label and the row value for this column. Every model data document input in the request represents a single row. This row will form an element in the rows array.