Skip to main content
Delphix

Migrating from Masking API v4 to v5 (KBA1824)

 

Migrating Masking APIs to v5

With the new API version (v5), the v4 API has been deprecated since all of the equivalent functionality have been covered.

This document explains how to make the equivalent calls in the v5 API that previously existed in the v4 API.

Reference documentation: 

Endpoints

Below are a set of v4 endpoints and how these are implemented in v5 Masking API. 

Note

Note:

The API is following basic CRUD methodology (Create, Read, Update, Delete). 
The POST is usually per Object when a GET may retrieve multiple Objects. 

Login

Log in to the masking engine.

v4 API

In the v4 API, the login endpoint would be used to acquire an authorization token in the response headers. This response token is then passed to all subsequent requests as auth_token in the request headers.

v5 API

In the v5 API, the login endpoint is used to acquire an authorization token in the response body. This response token is then passed to all subsequent requests as Authorization in the request headers.

  API v4 API v5
Type HTTP Request: GET HTTP Request: POST
URL dmsuite/apiV4/login?user={userID}&password={passwd} masking/api/logi
Request n/a {
"username": "MaskingUser",
"password": "Masking_123"
}
Response n/a {
   "Authorization": "892e3ade-411f-48fd-b86f-88201164f301"
}

Get Applications and Environments

Get a list of all applications, with links to their associated environments.

v4 API

In the v4 API, the knowledge of all applications and environments was useful to determine the URL with which to run a job. To facilitate the acquisition of that information, there was a single endpoint that would return information on all the applications and their associated environments.

v5 API

The v5 API does not require the application or environment to run a job though it still provides the ability to get all applications and to get all environments, albeit in two separate endpoints.

  API v4 API v5
Type HTTP Request: GET HTTP Request: GET
URL /dmsuite/apiV4/applications masking/api/applications
Request n/a n/a
Sample Body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<ApplicationsResponse>

<ResponseStatus>

<Status>SUCCESS</Status>

</ResponseStatus>

<Applications>

<Application>

<Name>demo</Name>

<Link href="applications/demo" rel="details"/>

<Environments>

<Link href="environments/1" rel="SAP"/>

</Environments>

<Environments>

<Link href="environments/37" rel="TEST"/>

</Environments>

</Application>

</Applications>

</ApplicationsResponse>

{

   "_pageInfo": {

       "numberOnPage": 2,

       "total": 2

   },

   "responseList": [

       {

           "applicationName": "app"

       },

       {

           "applicationName": "app_03PF3MB2"

       },

   ]

}

 

  API v4 API v5
Type   HTTP Request: GET
URL   masking/api/environments
Request   n/a
Sample Body  

{

   "_pageInfo": {

       "numberOnPage": 2,

       "total": 2

   },

   "responseList": [

       {

           "environmentId": 1,

           "environmentName": "env_CXK38D8U",

           "application": "app_MMY9VQIE",

           "purpose": "MASK",

           "isWorkflowEnabled": false

       },

       {

           "environmentId": 2,

           "environmentName": "env_H54CEQF7",

           "application": "app_EJDISGMI",

           "purpose": "TOKENIZE",

           "isWorkflowEnabled": false

       }

    ]

}

Getting Masking Jobs

Get a list of all jobs by application.

v4 API

In the v4 API, there was the ability to get a list of all jobs of all types, although only the ability to get masking jobs was supported. The acquisition of the list of jobs was based on the application the jobs resided in.

 

  API v4 API v5
Type HTTP Request: GET HTTP Request: GET
URL dmsuite/apiV4/applications/{applicationID}/jobs masking/api/masking-jobs
Request

n/a

n/a
Sample Body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<JobsResponse>

<ResponseStatus>

<Status>SUCCESS</Status>

</ResponseStatus>

<Jobs>

<Profiles>

<Profile>

<Name>OracleProfile</Name>

<Link rel="details" href="applications/demo/profilejobs/0"/>

<Status>Succeeded</Status>

</Profile>

</Profiles>

<Provisions/>

<Maskings>

<Masking>

<Name>OracleMasking</Name>

<Link rel="details" href="applications/demo/maskingjobs/1"/>

<Status>Succeeded</Status>

</Masking>

</Maskings>

<Certifys/>

</Jobs>

</JobsResponse>

{

   "_pageInfo": {

       "numberOnPage": 2,

       "total": 2

   },

   "responseList": [

       {

           "maskingJobId": 3,

           "jobName": "mask_PU12Z637",

           "rulesetId": 4,

           "createdBy": "admin",

           "createdTime": "2018-12-23T16:21:33.879+0000",

           "feedbackSize": 10000,

           "maxMemory": 1024,

           "minMemory": 1024,

           "multiTenant": false,

           "numInputStreams": 1,

           "onTheFlyMasking": false

       },

       {

           "maskingJobId": 5,

           "jobName": "mask_ORQIZWO3",

           "rulesetId": 5,

           "createdBy": "admin",

           "createdTime": "2018-12-23T16:22:41.951+0000",

           "feedbackSize": 10000,

           "maxMemory": 1024,

           "minMemory": 1024,

           "multiTenant": false,

           "numInputStreams": 1,

           "onTheFlyMasking": false

       }

   ]

}

Run Masking Job

Run masking job by ID and application.

v4 API

In the v4 API, the ability to run a masking job based on its application and its ID was supported. To run on-the-fly or multi-tenant jobs, the target connector could be passed into the request body.

v5 API

In the v5 API, the ability to run a job of any type is supported. The restriction of knowing the application for the job has been removed. Another difference between the (v4 and v5) APIs is that on-the-fly information is provided by updating the masking job to be on-the-fly, however, multi-tenant connector information is still specified via the request body.

  API v4 API v5
Type HTTP Request: POST HTTP Request: GET
URL dmsuite/apiV4/applications/{applicationID}/maskingjobs/{maskingJobID}/run HTTP Request: POST
Sample Body <MaskingsRequest/>

{

  "jobId": 3

}

Sample Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<MaskingsResponse>

<ResponseStatus>

<Status>SUCCESS</Status>

</ResponseStatus>

</MaskingsResponse>

{

   "executionId": 42,

   "jobId": 3,

   "status": "RUNNING",

   "startTime": "2018-12-27T17:06:48.670+0000"

}

Get Job Status

Check on the last execution status for a masking job.

v4 API

Finally, the v4 API allowed a user to check on the status of a masking job for the last time it had run.

v5 API

In the v5 API, we provide the ability to check the status of an execution for any job type. In later releases, this includes the ability to view the status of prior executions of a job. Note that the ID of the execution, rather than the job, which is returned when running a job, is necessary to view the status. If the execution ID has been lost, there is a way to get all executions for a given job, which will also be described below. Further note that in later releases even more granular information on the executions is available at other API endpoints, such as the execution-components endpoint.

  API v4 API v5
Type HTTP Request: POST HTTP Request: GET
URL dmsuite/apiV4/applications/{applicationID}/maskingjobs/{maskingjobID}/results masking/api/executions/{executionId}
Sample Body n/a n/a
Sample Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<MaskingsResponse>

<ResponseStatus>

<Status>SUCCESS</Status>

</ResponseStatus>

<Maskings>

<Masking>

<Name>OracleMasking</Name>

<Status>SUCCESS</Status>

<StartTime>16:04:00</StartTime>

<Duration>00:01:12</Duration>

<PreviousDuration>00:01:13</PreviousDuration>

<TablesTotal>1</TablesTotal>

<TablesProcessed>1</TablesProcessed>

<TablesRemaining>0</TablesRemaining>

<RowsProcessed>25</RowsProcessed>

<RowsRemaining>0</RowsRemaining>

<UpdatesRunning>4</UpdatesRunning>

<Respository>POSTGRESQL</Respository>

<Links>

<Link href="environments/1/connectors/1?DataSource=database" rel="SourceConnector"/>

<Link href="applications/demo/inventorys/Oracle?environmentId=1" rel="Inventory"/>

</Links>

</Masking>

</Maskings>

</MaskingsResponse>

{

   "executionId": 20,

   "jobId": 22,

   "status": "SUCCEEDED",

   "rowsMasked": 1000,

   "rowsTotal": 1000,

   "startTime": "2018-12-23T16:32:35.852+0000",

   "endTime": "2018-12-23T16:32:50.108+0000"

 

  API v4 API v5
Type   HTTP Request: GET
URL   masking/api/executions?job_id={jobId}
Sample Body   n/a
Sample Response  

{

   "_pageInfo": {

       "numberOnPage": 1,

       "total": 1

   },

   "responseList": [

       {

           "executionId": 18,

           "jobId": 20,

           "status": "SUCCEEDED",

           "rowsMasked": 51,

           "rowsTotal": 51,

           "startTime": "2018-12-23T16:31:30.707+0000",

           "endTime": "2018-12-23T16:31:47.497+0000"

       }

   ]

}

 

Related Articles

Documentation Links