API Export

Introduction to API Export

Functionality that exists in the application such as validating CDM JSON, ingesting FpML XML into CDM JSON and producing regulatory reports can be accessed directly using a RESTful service which is automatically deployed to the cloud on demand. As the application allows the 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 the model is further developed, the API can be re-exported on demand.

The API must be used in conjunction with an API-KEY to authorization to access which is created at export time. The same API-KEY will be used for all further exports and is unique per user workspace.

The APIs available in Rosetta Core are:

Exporting the service

To get started, in Rosetta Core open API Export by clicking on the link on the bottom panel. The list of supported APIs will be displayed. 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:

https://ui.rosetta-technology.io/api/promoted/{{service-name}}/{{owner-name}}/{{workspace-name}}/{{version}}/{{service-parameters}}
Parameter Description
service-name validation, ingest, reg-report or project
owner-name Owner of the workspace; system for public workspaces and the logged in user to user workspaces
workspace-name Name of the workspace that this API will be used for
version Version of the exported API. Currently, only latest is supported
service-parameters Parameters 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 Core UI (Using the Ingestion, 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.

<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.

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.

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.

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.

Parameter Description
model-type The 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:

[
        {
                "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:

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

Ingestion Service

The model defines synonyms which map external data models to types defined in a model expressed in Rosetta (e.g. CDM). 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.

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.

Parameter Description
ingestion-environment-name
The 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:

{
"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>
}
}

Regulation Report 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.

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

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

Parameter Description
regulatory-body The Body as defined by the model for example, ESMA for the CDM.
regulatory-corpus-list The 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:

[ {
"identifier" : {
        "regRegime" : "ESMA",
        "mandates" : [ "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"
                }
        ]
],
} ]

Projection Service

Coming soon

Updating the Model

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