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:
- API v4 Old
- Reference: Masking API Calls to Run a Masking Job (v4).
- API v5 New
- Reference: API Calls for Creating an Inventory (and other)
- Masking API Client: Masking API Client
Endpoints
Below are a set of v4 endpoints and how these are implemented in v5 Masking API.
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/> |
|
| Sample Response |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MaskingsResponse> <ResponseStatus> <Status>SUCCESS</Status> </ResponseStatus> </MaskingsResponse> |
|
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" } ] } |