Using the Common REST API Endpoints
The following section specifies the common operations that are applicable to all the Protegrity REST APIs.
The Base URL for each API will change depending on the version of the API being used. The following table specifies the version that you must use when executing the common operations for each API.
| REST API | Version in the Base URL <Version> |
|---|---|
| Policy Management | v2 |
| Encrypted Resilient Package | v1 |
Common REST API Endpoints
The following table lists the common operations for the Protegrity REST APIs.
| REST API | Description |
|---|---|
| /version | Retrieves the service versions that are supported by the Protegrity REST APIs on the ESA. |
| /health | This API request retrieves the health information for the Protegrity REST APIs and identifies whether the corresponding service is running. |
| /doc | This API request retrieves the API specification document. |
| /log | This API request retrieves current log level set for the corresponding REST API logs. |
| /log | This API request changes the log level for the REST API service during run-time. The level set through this resource is persisted until the corresponding service is restarted. This log level overrides the log level defined in the configuration. |
Retrieving the Supported Service Versions
This API retrieves the service versions that are supported by the corresponding REST API service on the ESA.
- Base URL
- https://{ESA IP address}/pty/<Version>/<API>
- Path
- /version
- Method
- GET
CURL request syntax
curl -H "Authorization: Bearer TOKEN" -X GET "https://{ESA IP address}/pty/<Version>/<API>/version"
In this command, Token indicates the JWT token used for authenticating the API.
Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/version"
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Sample CURL request
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/version"
This sample request uses the JWT token authentication.
Sample CURL response
{"version":"1.8.1","buildVersion":"1.8.1-alpha+605.gfe6b1d.master"}
Retrieving the Service Health Information
This API request retrieves the health information of the REST API service and identifies whether the service is running.
- Base URL
- https://{ESA IP address}/pty/<Version>/<API>
- Path
- /health
- Method
- GET
CURL request syntax
curl -H "Authorization: Bearer <TOKEN>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/health"
In this command, Token indicates the JWT token used for authenticating the API.
Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/health"
Authentication credentials
TOKEN - Enviroment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Sample CURL request
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v2/pim/health"
This sample request uses the JWT token authentication.
Sample CURL response
{
"isHealthy" : true
}
Where,
- isHealthy: true - Indicates that the service is up and running.
- isHealthy: false - Indicates that the service is down.
Retrieving the API Specification Document
This API request retrieves the API specification document.
- Base URL
- https://{ESA IP address}/pty/<Version>/<API>
- Path
- /doc
- Method
- GET
CURL request syntax
curl -H "Authorization: Bearer <Token>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/doc"
In this command, Token indicates the JWT token used for authenticating the API.
Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/doc"
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Sample CURL requests
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/doc"
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v1/rps/doc" -o "rps.yaml"
These sample requests uses the JWT token authentication.
Sample CURL responses
The Encrypted Resilient Package API specification document is displayed as a response. If you have specified the “-o” parameter in the CURL request, then the API specification is copied to a file specified in the command. You can use the Swagger UI to view the API specification document.
Retrieving the Log Level
This API request retrieves current log level set for the REST API service logs.
- Base URL
- https://{ESA IP address}/pty/<Version>/<API>
- Path
- /log
- Method
- GET
CURL request syntax
curl -H "Authorization: Bearer <TOKEN>" -X GET "https://{ESA IP address}/pty/<Version>/<API>/log"
In this command, Token indicates the JWT token used for authenticating the API.
Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://{ESA IP address}/pty/<Version>/<API>/log"
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Sample CURL request
curl -H "Authorization: Bearer ${TOKEN}" -X GET "https://10.10.101.43/pty/v2/pim/log"
This sample request uses the JWT token authentication.
Sample CURL response
{
"level": "INFO"
}
Setting Log Level for the REST API Service Log
This API request changes the REST API service log level during run-time. The level set through this resource persists until the corresponding service is restarted. This log level overrides the log level defined in the configuration.
- Base URL
- https://{ESA IP address}/pty/<Version>/<API>
- Path
- /log
- Method
- POST
CURL request syntax
curl -X POST "https://{ESA IP Address}/pty/<Version>/<API>/log" -H "Authorization: Bearer <TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"log level\"}"
In this command, Token indicates the JWT token used for authenticating the API.
Alternatively, you can also store the JWT token in an environment variable named TOKEN, as shown in the following command.
curl -X POST "https://{ESA IP Address}/pty/<Version>/<API>/log" -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"log level\"}"
Authentication credentials
TOKEN - Environment variable containing the JWT token.
For more information about creating a JWT token, refer to the section Using JSON Web Token (JWT).
Request body elements
log level
Set the log level. The log level can be set to SEVERE, WARNING, INFO, CONFIG, FINE, FINER, or FINEST.
Sample CURL request
curl -X POST "https://{ESA IP Address}/pty/v1/rps/log" -H "Authorization: Bearer ${TOKEN}" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"level\":\"SEVERE\"}"
This sample request uses the JWT token authentication.
Sample response
The log level is set successfully.