API Use

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:

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/validate/{{owner-name}}/{{workspace-name}}/latest/{{model-type}}

The content type header must be set to application/json.

JSON Validator Parameters

ParameterDescription
model-typeThe fully qualified type of the model object being validated which is the namespace followed by the name. For example, a type called Apple in a namespace called supermarket.fruits will be supermarket.fruits.Apple

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)"
    }
]

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/reg-report/{{owner-name}}/{{workspace-name}}/latest/{{model-type}}/{{regulatory-body}}/{{regulatory-corpus-list}}
The request's content type header must be set to application/json.

Regulation Report Parameters

ParameterDescription
regulatory-bodyThe Body as defined by the model, for example, ESMA for the CDM.
regulatory-corpus-listThe Corpus list for the regulatory report separated by /

For a report defined as report ESMA EMIR Article_9, the url will end with /ESMA/EMIR/Article_9.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
[ {
"identifier" : {
    "body" : "ESMA",
    "corpusList" : [ "MiFIR", "RTS_22" ],
    "name" : "ESMAMiFIR_RTS_22",
    "generatedJavaClassName" : "org.isda.cdm.blueprint.ESMAMiFIR_RTS_22Report"
},
"useCases" : [
    "useCase": "use case name",
    "dataSetName": "Name of the data set (e.g. DRR Test Data)",
    "fields": [ <list of fields in the report>
        {
        "name": "field name e.g. Report Timestamp",
        "value": "1981-04-13 07:51:20"
        }
    ]
],
} ]

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, for example FpML or application/json if ingesting a JSON document, for example ISDA Create.

Ingest Parameters

ParameterDescription
ingestion-environment-nameThe name of the environment set up to ingest the type of XML/JSON document. The current supported environments set up for the ISDA CDM model are: FpML_5_10, isdaCreateAll. For model extensions, where synonyms are defined to map other external models, the ingestion environment name will be set up and supplied directly to the user by the REGnosys support team

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
{
"rosettaModelInstance": { <Resulting model instance serialised to JSON> },
"inputValidation": {
    "errors": [ <If the ingested XML/JSON was not well formed, an error is output here> ]
},
"mappingReport": {
    "mappingResults": [ <A mapping result will exist for every data point in the ingested XML/JSON >
    {
        "success": true, <True if there were no errors, else False>
        "externalPath": {}, <Path of data point >
        "value": "634000000", <value of the field mapped>
        "internalPaths": {
            "Contract.tradableProduct.quantityNotation(0).quantity.amount": [ 634000000 ] <key/value of the path in the model and the value it was set to.>
        },
        "result": "Success", <Success or Fail>
        "externalPathString": "trade.swap.swapStream(0)[id=floatingLeg1].calculationPeriodAmount.calculation.notionalSchedule.notionalStepSchedule.initialValue" <The path from the ingested XML/JSON that is mapped>
    }
    ],
    "externalPaths": 110, <number of paths with a values assigned in the ingested XML/JSON>
    "successCount": 106, <number of successful mappings to the rosetta model>
    "completeness": 96.36363636363636 <percentage of completeness>
},
"validationReport": {
    "validationResults": [], <details about any validation failures>
    "success": true <True is the resulting model instance is valid and false if any validation rule failed>
}
}

Hosted API Overview

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

image

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.

If the model is updated in the user workspace, the API must be re-exported to pick up the changes.

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.

The Play button is only available for Read-Write models

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}}/{{version}}/{{service-parameters}}

API Export URL Arguments

ParameterDescription
service-namevalidation, ingest, reg-report or project
owner-nameOwner of the workspace; system for public workspaces and the logged in user to user workspaces
workspace-nameName of the workspace that this API will be used for
versionVersion of the exported API. Currently, only latest is supported
service-parametersParameters that differ per service

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 Translate, 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
31
32
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 version = "latest";
    String serviceParameters = <INSERT PARAMETERS>;

    String restEndpointUrl = String.format(
        "https://ui.rosetta-technology.io/api/promoted/%s/%s/%s/%s/%s",
            serviceName,
            ownerName,
            workspaceName,
            version,
            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:

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
ParameterDescription
Docker Registryregnosys-docker-registry.jfrog.io
Image Nameregnosys/rosetta-{{service}}/{{service-particulars}}
Image Version{{image version}}

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

docker login regnosys-docker-registry.jfrog.io -u USER -p TOKEN

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 regnosys-docker-registry.jfrog.io/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
ParameterValue
Env NameDefault
APP_PORT9000
ADMIN_PORT8001

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 regnosys-docker-registry.jfrog.io/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.

Screenshot of the Open API

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
ParameterValue
document-namemy-sample-data-2019
version0.1
envproduction or sandbox

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.

Translate {{synonym}} JSON to CDM

To transform a {{synonym}} JSON to CDM use the http://localhost:9000/api/swagger#/RosettaIngest/translateJson 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
ParameterValue
document-namemy-sample-data-2019
version0.1
envproduction

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

Translate {{synonym}} XML to CDM

To transform a {{synonym}} XML to CDM, use the http://localhost:9000/api/swagger#/RosettaIngest/translateXml 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 CDM 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
ParameterValue
bodysample-standards-body
corpusListcorpus1/corpus2
inputModelTypecom.legal.info.ASamplep
name{{sample-standards-body}}{{the-corpus-list}}
classNamemy.regulation.body.corpus.blueprint.{{sample-standards-body}}{{the-corpus-list}}

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 CDM document

To run {{report}} on a CDM document or array of CDM 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 CDM 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 CDM document input in the request represents a single row. This row will form an element in the rows array.