This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Version 1 (V1) Application Protector API on REST

Describes the Version 1 AP REST protector APIs that are available for protection and unprotection of data. It also lists the error handling capabilities provided by the AP API on REST.

1: List of REST APIs

1.1: HTTP GET version
1.2: HTTP POST protect
1.3: HTTP POST unprotect
1.4: HTTP POST reprotect
1.5: HTTP Headers

2: Error Handling for v1 API
3: V1 AP REST HTTP Response Codes

1 - List of REST APIs

Lists the AP REST APIs.

This section describes the AP REST APIs available for protection and unprotection of data.

1.1 - HTTP GET version

This API displays the version of the AP REST protector API being used.

URI: https://hostname/rest-v1/version
Method: GET
Parameters: Hostname: Host name of the endpoint, as defined in the AP-REST deployment; Resource: The resource to be used, which is /rest-v1/version
Result: This function returns the current version of the AP REST protector API.

Response

Status	Response
200	`{"version":"10.0.0.0.13","components":{"jpepVersion":"10.0.0.0.15","coreVersion":"1.1.0+76.ge82e5.1.1"}}`

Example

$ curl 'https://<HostName>/rest-v1/version' --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key

1.2 - HTTP POST protect

This API returns protected data.

URI: https://hostname/rest-v1/protect
Method: POST
Parameters: Hostname: Host name of the endpoint, as defined in the AP-REST deployment; Resource: The resource to be used, which is /rest-v1/protect
Result: This API returns protected data.

The input data must always be Base64 encoded.

Example 1 - without external IV and external tweak

$ curl --location --request POST 'https://<hostname>/rest-v1/protect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key  --data '{ 
  "protect": {
    "policyusername": "Uername",
    "dataelementname": "DataElement1",
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
        },
                {
          "id": 2,
          "content": "AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
        }
      ]
    }
  }
}'

Response 1 - without external IV and external tweak

The following response appears for the status code 200, if the API is invoked successfully.

{
   "protect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"AGoAZABzAHIAdQBlAGMAagBaAEMAMQAyADMANA=="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"AGoAZABzAHIAdQBlAGMAagBaAEMAMQAyADMANA=="
            }
         ]
      }
   }
}

Example 2 - with external IV

$ curl --location --request POST 'https://<hostname>/rest-v1/protect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key  --data '{ 
  "protect": {
    "policyusername": "Uername",
    "dataelementname": "DataElement1",
    "externaliv": "ZXh0ZXJuYWpdg=="
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "RW5eEN2RGZZaw=="
        },
                {
          "id": 2,
          "content": "cmZBcnJTRg=="
        }
      ]
    }
  }
}'

Response 2 - with external IV

The following response appears for the status code 200, if the API is invoked successfully.

{
   "protect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"OG8xZW0QlQ3MQ=="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"blg2Qm5Ddg=="
            }
         ]
      }
   }
}

Example 3 - with external tweak

$ curl --location --request POST 'https://<hostname>/rest-v1/protect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key  --data '{ 
  "protect": {
    "policyusername": "Uername",
    "dataelementname": "DataElement2_FPE",
    "externaltweak": "ZXh0ZXJuYWpdg=="
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "RW5eEN2RGZZaw=="
        },
                {
          "id": 2,
          "content": "cmZBcnJTRg=="
        }
      ]
    }
  }
}'

Response 3 - with external tweak

The following response appears for the status code 200, if the API is invoked successfully.

{
   "protect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"MHM4OVpsRndIbA=="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"VzFsNmd1Ng=="
            }
         ]
      }
   }
}

1.3 - HTTP POST unprotect

This API unprotects the protected data.

URI: https://hostname/rest-v1/unprotect
Method: POST
Parameters: Hostname: Host name of the endpoint, as defined in the AP-REST deployment; Resource: The resource to be used, which is /rest-v1/unprotect
Result: This API returns unprotected data.

The input data must always be Base64 encoded.

Example 1 - without external IV and external tweak

$ curl --request POST 'https://<hostname>/rest-v1/unprotect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key  --data '{ 
  "unprotect": {
    "policyusername": "UserName",
    "dataelementname": "DataElement1",
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
        },
                {
          "id": 2,
          "content": "AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
        }
      ]
    }
  }
}'

Response 1 - without external IV and external tweak

The following response appears for the status code 200, if the API is invoked successfully.

{
   "unprotect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/8",
               "returntype":"success",
               "content":"AGwATgBWAEwATAByAFIAUAB2AGcAMQAyADMANA=="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/8",
               "returntype":"success",
               "content":"AGwATgBWAEwATAByAFIAUAB2AGcAMQAyADMANA=="
            }
         ]
      }
   }
}

Example 2 - with external IV

$ curl --request POST 'https://<hostname>/rest-v1/unprotect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key  --data '{ 
  "unprotect": {
    "policyusername": "UserName",
    "dataelementname": "DataElement1",
    "externaliv": "ZXh0ZXJuYWpdg=="
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "OG8xZW0QlQ3MQ=="
        },
                {
          "id": 2,
          "content": "blg2Qm5Ddg=="
        }
      ]
    }
  }
}'

Response 2 - with external IV

The following response appears for the status code 200, if the API is invoked successfully.

{
   "unprotect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/8",
               "returntype":"success",
               "content":"RW5eEN2RGZZaw=="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/8",
               "returntype":"success",
               "content":"cmZBcnJTRg=="
            }
         ]
      }
   }
}

Example 3 - with external tweak

$ curl --request POST 'https://<hostname>/rest-v1/unprotect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key  --data '{ 
  "unprotect": {
    "policyusername": "UserName",
    "dataelementname": "DataElement2_FPE",
    "externaltweak": "ZXh0ZXJuYWpdg=="
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "MHM4OVpsRndIbA=="
        },
                {
          "id": 2,
          "content": "VzFsNmd1Ng=="
        }
      ]
    }
  }
}'

Response - with external tweak

The following response appears for the status code 200, if the API is invoked successfully.

{
   "unprotect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/8",
               "returntype":"success",
               "content":"RW5eEN2RGZZaw=="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/8",
               "returntype":"success",
               "content":"cmZBcnJTRg=="
            }
         ]
      }
   }
}

1.4 - HTTP POST reprotect

This API reprotects the data.

URI: https://hostname/rest-v1/reprotect
Method: POST
Parameters: Hostname: Host name of the endpoint, as defined in the AP-REST deployment; Resource: The resource to be used, which is /rest-v1/reprotect
Result: This API reprotects the data.

The input data must always be Base64 encoded.

Example 1 - without external IV and external tweak

$ curl --request POST 'https://<hostname>/rest-v1/reprotect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt  --key iap-rest-client.key  --data '{ 
  "reprotect": {
    "policyusername": "UserName",
    "olddataelementname": "DataElement1", "newdataelementname": "DataElement2",
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
        },
                {
          "id": 2,
          "content": "AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
        }
      ]
    }
  }
}'

Response 1 - without external IV and external tweak

The following response appears for the status code 200, if the API is invoked successfully.

{
   "reprotect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANA=="
            }
         ]
      }
   }
}

Example 2 - with external IV

curl --location --request POST 'https://<hostname>/rest-v1/reprotect' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt --key iap-rest-client.key  --data '{
  "reprotect": {
    "policyusername": "UserName",
    "olddataelementname": "DataElement1",
    "newdataelementname": "DataElement2","oldexternaliv":"MTIzNDVhYmNzIyQlXiM2Nzg5MFMrTlNBQkNTRA=","newexternaliv":"MTIzNDVhYmNzIyQlXiM2Nzg5MFMrTlNBQkNTRA="
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "MTA1MTYwNTk1MjE5OTY3OTU="
        },
                {
          "id": 2,
          "content": "MTA1MTYwNTk1MjE5OTY3OTU="
        }
      ]
    }
  }
}'

Response 2 - with external IV

The following response appears for the status code 200, if the API is invoked successfully.

{
   "reprotect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"Q09udGFpbmVyVGVhbTEyMzQ1Njc="
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"AFAAcgBvAHQAZQBnAHIAaQB0AHkAMQAyADMANAA1"
            }
         ]
      }
   }
}

Example 3 - with external tweak

curl --location --request POST 'https://<hostname>/rest-v1/reprotect' \
--header 'Host: <hostname>' \
--connect-to  "<hostname>:443:<AWS LoadBalancer>:443"  \
--header 'Content-Type: application/json' \
 --cacert iap-rest-ca.crt --cert iap-rest-client.crt --key iap-rest-client.key  --data '{
  "reprotect": {
    "policyusername": "UserName",
    "olddataelementname": "DataElement1",
    "newdataelementname": "DataElement2","oldexternaltweak":"MTIzNDVhYmNzIyQlXiM2Nzg5MFMrTlNBQkNTRA=","newexternaltweak":"MTIzNDVhYmNzIyQlXiM2Nzg5MFMrTlNBQkNTRA="
    "bulk":{
      "id": 1,
      "data": [
        {
          "id": 1,
          "content": "MTA1MTYwNTk1MjE5OTY3OTU="
        },
                {
          "id": 2,
          "content": "MTA1MTYwNTk1MjE5OTY3OTU="
        }
      ]
    }
  }
}'

Response 3 - with external tweak

The following response appears for the status code 200, if the API is invoked successfully.

{
   "reprotect":{
      "bulk":{
         "id":1,
         "returntype":"success",
         "data":[
            {
               "id":1,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"AFAAYQByAGgAbQBoAFAAawBMAGcAZQBaAFgAaABtAGEAcg"
            },
            {
               "id":2,
               "returncode":"/rest-v1/returncodes/id/6",
               "returntype":"success",
               "content":"ADEAMgAzADQANQA2ADcAOAA5ADA"
            }
         ]
      }
   }
}

1.5 - HTTP Headers

Overview about HTTP headers.

The client should send the required HTTP headers to the server to specify the type of data being sent in the payload. The content type also specifies the type of result being sent by the server to the client.

To send a JSON request and get a JSON response, specify the following HTTP header:

Content-Type: application/json

2 - Error Handling for v1 API

For record error handling, the bulk id and data id fields are used, which enable tracking of the errors from the client side.

The following table lists the record error handling status codes, which are sent from the server to the client.

Status Code	Responses
Success	`{ "bulk":{ "id":1, "returntype":"success", "data":[ { "id":1, "returncode":"/rest-v1/returncodes/id/6", "returntype":"success", "content":"AGoAZABzAHIAdQBlAGMAagBaAEMAMQAyADMANA==" }, { "id":2, "returncode":"/rest-v1/returncodes/id/6", "returntype":"success", "content":"AGoAZABzAHIAdQBlAGMAagBaAEMAMQAyADMANA==" } ] } }`
Success, with warning	`{ "bulk":{ "id":1, "returntype":"warning", "data":[ { "id":1, "returntype":"warning", "content":null }, { "id":2, "returntype":"warning", "content":null } ] } }`
Error type of log return code	`{ "bulk":{ "id":1, "returntype":"error", "data":[ { "id":1, "message":"Data is too short to be protected/unprotected.", "returncode":"/rest-v1/returncodes/id/22", "returntype":"error" }, { "id":2, "message":"Data is too short to be protected/unprotected.", "returncode":"/rest-v1/returncodes/id/22", "returntype":"error" } ] } }`
Error type of log return code (different)	`{ "bulk":{ "id":1, "returntype":"error", "data":[ { "id":1, "message":"Data is too short to be protected/unprotected.", "returncode":"/rest-v1/returncodes/id/22", "returntype":"error" }, { "id":2, "returncode":"/rest-v1/returncodes/id/6", "returntype":"success", "content":"AGoAZABzAHIAdQBlAGMAagBaAEMAMQAyADMANA==" } ] } }`

For more information about the Log Return codes, refer to the section Log return codes.

3 - V1 AP REST HTTP Response Codes

Lists the response codes generated for the HTTP REST requests sent to the v1 AP REST APIs. It also specifies the corresponding audit code generated in the logs.

Error Messages	Operation	Audit Code in Logs	HTTP Response Code
Failed to decode Base64	Protect Unprotect Reprotect	No audit code generated	400
The content of the input data is not valid	Protect Unprotect Reprotect	44	400
Unsupported algorithm or unsupported action for the specific data element	Protect Unprotect Reprotect	26	400
Data is too long to be protected/unprotected	Protect Unprotect Reprotect	23	400
Data is too short to be protected/unprotected	Protect Unprotect Reprotect	22	400
The user does not have the appropriate permissions to perform the requested operation	Protect Unprotect Reprotect	3	400
The data element could not be found in the policy	Protect Unprotect Reprotect	1	401
The username could not be found in the policy	Protect Unprotect Reprotect	2	400
Data unprotect operation failed. with correlationId <CorrelationID>	Unprotect	9	400
Tweak input is too long. with correlationId <Correlation ID>	Protect Unprotect Reprotect	15	200
Failed to send logs, connection refused ! with correlationId <Correlation ID>	Protect Unprotect Reprotect	51	400
Policy not available with correlationId <Correlation ID>	Protect Unprotect Reprotect	31	400