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.
|
|
application/json
.JSON Validator Parameters ¶
Parameter | Description |
---|---|
rosetta-object-type | The fully qualified type of the Rosetta 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:
|
|
The example of the output could look like this:
|
|
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.
|
|
application/json
.Run Function Parameters ¶
Parameter | Description |
---|---|
rosetta-function-type | The fully qualified type of the Rosetta function to run, which is the namespace followed by the function name. For example, a func called Add in a namespace called demo.math.functions will be demo.math.functions.Add |
The input JSON data should match the arguments of the function. For example, given the following Rosetta function
|
|
Input JSON example:
|
|
Result JSON example:
|
|
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.
|
|
application/json
.Regulation Report Parameters ¶
Parameter | Description |
---|---|
namespace | The namespace where the Report object is defined in the model, for example, demo.emissions for the report EuropeanParliament EmissionPerformanceStandardsEU in the Demonstration Model. |
regulatory-body | The Body as defined by the model, for example, EuropeanCommission for the Demonstration Model. |
regulatory-corpus-list | The Corpus list for the regulatory report separated by / , for example,93/59/EC . |
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:
|
|
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.
|
|
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 ¶
Parameter | Description |
---|---|
ingestion-environment-name | The name of the environment set up to ingest the type of XML/JSON document. 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:
|
|
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.
Play
button is only available for Read-Write modelsSelect 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:
|
|
API Export URL Arguments ¶
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 |
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:
- 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. - Export a service as a REST API and invoke programmatically using
JAVA
utility libraries. - 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.
|
|
See below for a simple example in Java.
|
|
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 ¶
Parameter | Description |
---|---|
Docker Registry | europe-west1-docker.pkg.dev/production-208613/{{client-name}} |
Image Name | regnosys/rosetta-{{service}}/{{service-particulars}} |
Image Version | {{image version}} |
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 ¶
Parameter | Value |
---|---|
Env Name | Default |
APP_PORT | 9000 |
ADMIN_PORT | 8001 |
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 ¶
Parameter | Value |
---|---|
document-name | my-sample-data-2019 |
version | 0.1 |
env | production 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.
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 ¶
Parameter | Value |
---|---|
document-name | my-sample-data-2019 |
version | 0.1 |
env | production |
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 ¶
Parameter | Value |
---|---|
body | sample-standards-body |
corpusList | corpus1/corpus2 |
inputModelType | com.legal.info.ASamplep |
name | {{sample-standards-body}}{{the-corpus-list}} |
className | my.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 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.