Quick Start#

Download the library#

RPS API Library can be downloaded from GitHub, Nuget package and soon from npm.

  • On GitHub, the library can be downloaded by clicking on Clone and choosing the preferred method (https download link, .zip package, etc.).
  • On Nuget, command lines are provided to download the repository, using the Package Manager, .NET CLI or other clients.
  • On npm Use npm to install the RPS Engine Client library: npm i rps-engine-client-js.
  • On Maven use dependency to groupId ch.regdata.rps.engine.client and artifactId rps-engine-api-client in pom.xml.

Configure the transformation#

In order to use the RPS API Library you need to have a valid transformation configuration in RPS CoreConfiguration. You can find instructions on how to create your first target and configuration on the Transform Quick Start documentation, points 1) and 2).

But for the purpose of this quick-start guide we advise you either manually create a transformation configuration from this JSON configuration file, and by following this tutorial.

Or simply use the configuration template predefined for this quick-start guide. The configuration template is usable as so, simply click CREATE NEW FROM TEMPLATES from the targets list page under TRANSFORM>TARGETS and selects REGDATA examples / API library example configuration. A new target called "REGDATA examples" will be created and will contain the "API library example" configuration, which provides examples of protection and unprotection of simple data instances (name, birth date...) using anonymization, encryption or tokenization.

Configure RPSEngine class#

In this section we see how to configure the RPSEngine class in the RPS API Library in order to use the transformation configuration you just created. You have to replace following parameters with the values you retrieved when you created the transformation configuration in RPS CoreConfiguration:

  • {API_KEY_OF_CONFIGURATION} = It is the API Key of the transformation configuration
  • {SECRET_KEY_OF_CONFIGURATION} = It is the Secret Key of the transformation configuration
  • {TRANSFORM_ENDPOINT} = It is the RPS transformation services endpoint
  • {AUTH_ENDPOINT} = It is the RPS OAuth2 authentication services endpoint

C# .NET Framework#

In a .NET Framework environment, the creation of RPS Engine classes must be done manually as it is shown in below code example:

// Configuration options for RPS Engine Client library.
var engineClientOptions = new EngineClientOptions
{
  EngineHostName = "{TRANSFORM_ENDPOINT}",// Example: "https://engine.rpsprod.ch"
  IdentityServerHostName = "{AUTH_ENDPOINT}",// Example: "https://identity.rpsprod.ch"
  ApiKey = "{API_KEY_OF_CONFIGURATION}", // Example: "518155d0-4774-467c-b891-6ebd3ea07f08"
  SecretKey = "{SECRET_KEY_OF_CONFIGURATION}" // Example: "75582a544bda425d956390844755f60369b9866026d8485aa49f7edcfe986bb1"
  Timeout = TimeSpan.FromMinutes(5) // Timeout to wait for answer from the RPS Engine API before throwing timeout exception
};

var engineJsonRestApiClient = new EngineJsonRestApiClient(
  engineClientOptions,
  new ClientCredentialsTokenProvider(engineClientOptions));

// RPS Engine context resolver is optional class.
// Using to resolve rights & processing contexts from any sources (JSON, XML, Database, etc.) by name (key).
// As example, we implement the RPSEngineContextJsonFileProvider to resolve both contexts from JSON files.
// You may implement your own provider based on the IRPSEngineContextProvider interface.
var rpsEngineContextResolver = new RPSEngineContextResolver(
  new RPSEngineContextJsonFileProvider("RightsContext.json", "ProcessingContext.json"));

// Final class. This class is used to create request(s) and call RPS Engine API.
RPSEngine rpsEngine = new RPSEngine(
  engineProvider: engineJsonRestApiClient,
  converter: new RPSEngineConverter(),
  contextResolver: rpsEngineContextResolver);

C# .NET Core#

In a .NET Core environment, configuration is much easier as the creation of RPS Engine classes is automatic. You will still need to modify some fields in order to match your configuration. In the API Library you downloaded, in the file Examples>appsettings.json, change the following fields of the RPSEngine object:

...
  "RPSEngine": {
    "EngineHostName": "{TRANSFORM_ENDPOINT}",
    "IdentityServerHostName": "{AUTH_ENDPOINT}",
    "Timeout": "00:05:00",
    "ApiKey": "{API_KEY_OF_CONFIGURATION}",
    "SecretKey": "{SECRET_KEY_OF_CONFIGURATION}"
  },
...

Along with the file Examples>Program.cs that is already included in your repository, .NET Core will automatically create the classes needed by RPS Engine.

Javascript#

In Javascript the creation of RPSEngine classes must be done manually (tokenProvider created with engineAuthEndpoint, clientId, and clientSecret, engineClient created with config.baseURL and tokenProvider - instance of TokenProvider class) as it is shown in below code example:

// import TokenProvider and EngineClient classes from NPM package
const {TokenProvider, EngineClient} = require('rps-engine-client-js/lib')

/**
 RPSEngine configs
 */
const RPSEngine = {
  ENGINE_TRANSFORM_API_URL: 'https://engine.rpsprod.ch/api/',
  IDENTITY_SERVER_HOST_NAME: 'https://identity.rpsprod.ch/',
  API_KEY: 'ee91981e-22f0-476c-a7d0-adddfcea462b',
  SECRET_KEY: '2df4b1ad5dbb4ac99b8a0692a4e5a2ed4987e07d1c124f71afa29516e470508b'
}

/**
 Creates an instance of the class TokenProvider
 */
const tokenProvider = new TokenProvider({
  identityServerHostName: RPSEngine.IDENTITY_SERVER_HOST_NAME,
  clientId: RPSEngine.API_KEY,
  clientSecret: RPSEngine.SECRET_KEY
})

/**
 Creates an instance of the class EngineClient
 */
const engineClient = new EngineClient({
  config: {
    baseURL: RPSEngine.ENGINE_TRANSFORM_API_URL // since v3.11.x we should put the full URL to the Engine API
  },
  tokenProvider
})

module.exports = {
  tokenProvider, // export TokenProvider instance
  engineClient // export EngineClient instance
}

Java#

In Java the creation of RPSEngine classes must be done manually as well, as shown in the example below:

public abstract class EngineProviderFactory {
    public static HttpClientEngineProvider getEngineProvider() {
        // Configuration options for RPS Engine Client library.
        final String engineHostName = "https://engine.rpsprod.ch";// Example: "https://engine.rpsprod.ch"
        final String identityHostName = "https://identity.rpsprod.ch";  // Example: "https://identity.rpsprod.ch",
        final String apiKey = "*********************"; // Example: "518155d0-4774-467c-b891-6ebd3ea07f08"
        final String secretKey = "********************"; // Example: "75582a544bdasa23easdasdaadssd5f60369b9866026d8485aa49f7edcfe986bb1"

        // Set the engine provider with connection details
        HttpClientEngineProvider engineProvider = new HttpClientEngineProvider();
        engineProvider.setApiKey(apiKey);
        engineProvider.setSecretKey(secretKey);
        engineProvider.setIdentityHost(identityHostName);
        engineProvider.setEngineHost(engineHostName);

        return engineProvider;
    }
}

Transform data#

You are now ready to transform data by using the RPS API Library. In order to do that you can follow the examples of usage.