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

Return to the regular view of this page.

Common APIs

Standard operational endpoints available on the service.

1: API Specification

2: Health Probes

2.1: Liveness Probe

2.2: Readiness Probe

2.3: Health Check

3: Log Level API

3.1: Log Level API

3.2: Log Level API

4: Version API

These endpoints provide operational capabilities such as retrieving the API specification, managing log levels, checking version information, and monitoring service health.

1 - API Specification

Returns the OpenAPI specification for the Data Discovery API.

Method

GET

URL

http://{Host Address}/doc

Query Parameters

None

Sample Request

curl -X GET "http://<Host_address>/doc"

import requests
    
    url = "http://<Host_address>/doc"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    print("Response YAML:", response.text)

URL: GET `http: //<Host_address>/doc`

Sample Response

Returns the OpenAPI specification in YAML format. The following shows a partial example:

openapi: 3.0.3
info:
  title: Protegrity Classification Service API
  version: v2
servers:
- url: /pty/data-discovery/v2
components:
  schemas:
    TextAggregatedResponse:
      allOf:
      # ... (abbreviated)
paths:
  /classify/text:
    post:
      summary: Classify free-form text input.
      tags: [Classify
]
  /classify/tabular:
    post:
      summary: Classify tabular CSV input.
      tags: [Classify
]
  /version:
    get:
      summary: Returns runtime version information.
      tags: [Common
]
  /log:
    get:
      summary: Get current runtime log level.
      tags: [Common
]
  # ... (full specification continues)

Response Codes

Code	Description
200	The OpenAPI specification is returned in YAML format.

2 - Health Probes

Kubernetes-style health probe endpoints for monitoring state of the service.

The following are the health probe endpoints that can be used on platforms such as Kubernetes.

Endpoint	Purpose
Liveness (`/live`)	Indicates that the service can handle HTTP requests.
Readiness (`/ready`)	Indicates that the service is initialized and ready to serve requests.
Health (`/health`)	Indicates that the service is running and all components are functioning properly.

2.1 - Liveness Probe

Indicates that the service is running and can handle HTTP requests.

Method

GET

URL

http://{Host Address}/live

Used by Kubernetes as a liveness probe.

Query Parameters

None

Sample Request

curl -X GET "http://<Host_address>/live"

import requests
    
    url = "http://<Host_address>/live"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)

URL: GET `http: //<Host_address>/live`

Response Codes

Code	Description
204	Service can handle requests.

2.2 - Readiness Probe

Indicates the service is initialized and ready to serve requests.

Method

GET

URL

http://{Host Address}/ready

This is used by Kubernetes as a readiness probe.

Query Parameters

None

Sample Request

curl -X GET "http://<Host_address>/ready"

import requests
    
    url = "http://<Host_address>/ready"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)

URL: GET `http: //<Host_address>/ready`

Response Codes

Code	Description
204	Service is fully initialized and can handle requests.
503	Service is not yet ready to serve requests.

2.3 - Health Check

Indicates that the service is running and all components are functioning correctly.

Method

GET

URL

http://{Host Address}/health

Returns service health status including individual component-level checks.

Query Parameters

None

Sample Request

curl -X GET "http://<Host_address>/health"

import requests
    
    url = "http://<Host_address>/health"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)

URL: GET `http: //<Host_address>/health`

Sample Response

{
    "isHealthy": true,
    "checks": [
        {
            "isHealthy": true,
            "output": {
                "isHealthy": true,
                "checks": [
                    {
                        "passed": true,
                        "output": "Pattern Classifier found",
                        "componentType": "engine",
                        "componentName": "Pattern Classifier"
                    },
                    {
                        "passed": true,
                        "output": "Pattern Classifier engine initialized",
                        "componentType": "engine",
                        "componentName": "Pattern Classifier"
                    },
                    {
                        "passed": true,
                        "output": "Dummy classification is responsive",
                        "componentType": "engine",
                        "componentName": "Pattern Classifier"
                    }
                ]
            },
            "componentType": "classification-provider",
            "componentName": "Pattern"
        },
        {
            "isHealthy": true,
            "output": {
                "isHealthy": true,
                "checks": [
                    {
                        "passed": true,
                        "output": "PII Classifier model initialized",
                        "componentType": "model",
                        "componentName": "PII Classifier"
                    },
                    {
                        "passed": true,
                        "output": "Dummy classification is responsive",
                        "componentType": "engine",
                        "componentName": "Context Classifier"
                    }
                ]
            },
            "componentType": "classification-provider",
            "componentName": "Context"
        }
    ]
}

Response Fields Description

Name	Type	Description
`isHealthy`	boolean	`true` if all components are functioning properly.
`checks`	array	List of component health checks.
`checks[].isHealthy`	boolean	`true` if this component is healthy.
`checks[].componentType`	string	Type of the component (e.g., `classification-provider`).
`checks[].componentName`	string	Name of the component (e.g., `Pattern`).
`checks[].output`	object	Detailed output for this component’s checks.
`checks[].output.isHealthy`	boolean	`true` if all of this component’s internal checks passed.
`checks[].output.checks`	array	List of individual sub-checks for this component.
`checks[].output.checks[].passed`	boolean	`true` if this sub-check passed.
`checks[].output.checks[].output`	string	Description of the sub-check result.
`checks[].output.checks[].componentType`	string	Type of the element checked.
`checks[].output.checks[].componentName`	string	Name of the element checked.

Response Codes

Code	Description
200	Service is running normally.
503	Service is unhealthy. Its components may be initializing or may need a restart.

3 - Log Level API

Retrieve or update the runtime log level.

3.1 - Log Level API

Retrieve the runtime log level.

Method

GET

URL

http://{Host Address}/log

Returns the current runtime logging level.

Query Parameters

None

Sample Request

curl -X GET "http://<Host_address>/log"

import requests
    
    url = "http://<Host_address>/log"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)

URL: GET `http://<Host_address>/log`

Sample Response

{
  "level": "info"
}

Response Fields Description

Name	Description
`level`	The current log level. Possible values: `debug`, `info`, `warn`.

Response Codes

Code	Description
200	Log level information retrieved successfully.

3.2 - Log Level API

Update the runtime log level.

Method

POST

URL

http://{Host Address}/log

Updates the runtime logging level.

Request Body

Name	Type	Required	Description
level	string	Yes	The log level to set. Possible values: `debug`, `info`, `warn`.

Sample Request

curl -X POST "http://<Host_address>/log" \
       -H "Content-Type: application/json" \
       -d '{"level": "debug"}'

import requests
    
    url = "http://<Host_address>/log"
    payload = {"level": "debug"}
    headers = {"Content-Type": "application/json"}
    response = requests.post(url, json=payload, headers=headers, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)

URL: POST `http: //<Host_address>/log`
   Body (JSON): {
       "level": "debug"
   }

Sample Response

{
    "level": "debug"
}

Response Fields Description

Name	Description
level	The updated log level.

Response Codes

Code	Description
200	Log level updated successfully.
500	An error occurred (e.g., invalid log level specified).

Note: The service currently returns 500 for invalid log level values. The OpenAPI spec defines 400 for this case — this is a known discrepancy to be addressed in a future release.

4 - Version API

View runtime version information.

Method

GET

URL

http://{Host Address}/version

Query Parameters

None

Sample Request

curl -X GET "http://<Host_address>/version"

import requests
    
    url = "http://<Host_address>/version"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)

URL: GET `http: //<Host_address>/version`

Sample Response

{
  "version": "2.0.0",
  "buildVersion": "2.0.0.374.8047721c"
}

Response Fields Description

Name	Description
`version`	Semantic version of Data Discovery in the `MAJOR.MINOR.PATCH` format.
`buildVersion`	Full build version string in the `MAJOR.MINOR.PATCH.BUILD.COMMITHASH` format.

Response Codes

Code	Description
200	Version information retrieved successfully.