Get Deep Dependency Status
GET
/v1/rest/status/deep
Description: Returns comprehensive connectivity and health status of all downstream dependencies by performing full health checks. This provides detailed diagnostics about each dependency's operational status.
What is this endpoint used for?
This endpoint provides thorough dependency health validation for diagnostics and troubleshooting:
- Detailed Diagnostics: Perform full operational health checks against all downstream services, not just connectivity
- Troubleshooting: Identify the root cause of failures by exercising actual dependency operations
- Manual Investigation: Use during incident response to determine if a dependency is partially or fully degraded
- Post-Deployment Validation: Confirm that all dependencies are fully functional after a deployment or configuration change
- Comprehensive Health Report: Get a complete picture of the service ecosystem health
No Authentication Required: This endpoint does NOT require authentication, making it accessible for operations teams and monitoring systems.
Performance Consideration: This endpoint performs full health checks against all dependencies, which takes approximately 2-5 seconds to complete. It should NOT be used for frequent automated polling or load balancer health checks. For regular monitoring, use the Shallow Status endpoint instead.
Code Examples
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Collections.Generic;
public class DeepStatusClient
{
private readonly HttpClient _httpClient;
private readonly string _baseUrl = "https://your-api-domain.com";
public DeepStatusClient()
{
_httpClient = new HttpClient();
_httpClient.BaseAddress = new Uri(_baseUrl);
// Longer timeout for deep checks (2-5 seconds expected)
_httpClient.Timeout = TimeSpan.FromSeconds(30);
}
public async Task<DependencyCheckResponse> CheckDeepStatusAsync()
{
try
{
// Make the GET request (no authentication required)
var response = await _httpClient.GetAsync("/v1/rest/status/deep");
var responseBody = await response.Content.ReadAsStringAsync();
var options = new JsonSerializerOptions
{
PropertyNameCaseInsensitive = true
};
var result = JsonSerializer.Deserialize<DependencyCheckResponse>(responseBody, options);
// HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
if (response.IsSuccessStatusCode)
{
Console.WriteLine("All dependencies passed deep health checks.");
}
else if ((int)response.StatusCode == 503)
{
Console.WriteLine("One or more dependencies failed deep health checks:");
foreach (var dep in result.Dependencies)
{
if (dep.Status != "Healthy")
{
Console.WriteLine($" - {dep.Name}: {dep.Status}");
Console.WriteLine($" Message: {dep.Message}");
}
}
}
return result;
}
catch (TaskCanceledException)
{
Console.WriteLine("Deep status check timed out. The service may be under heavy load.");
throw;
}
catch (Exception ex)
{
Console.WriteLine($"Deep status check failed: {ex.Message}");
throw;
}
}
}
public class DependencyCheckResponse
{
public string Status { get; set; }
public List<DependencyStatus> Dependencies { get; set; }
}
public class DependencyStatus
{
public string Name { get; set; }
public string Status { get; set; }
public string Message { get; set; }
}
// Example usage:
var client = new DeepStatusClient();
var statusResponse = await client.CheckDeepStatusAsync();
Console.WriteLine($"Overall Status: {statusResponse.Status}");
Console.WriteLine("Dependency Details:");
foreach (var dep in statusResponse.Dependencies)
{
var indicator = dep.Status == "Healthy" ? "[OK]" : "[FAIL]";
Console.WriteLine($" {indicator} {dep.Name}: {dep.Status} - {dep.Message}");
}
Imports System.Net.Http
Imports System.Text.Json
Imports System.Text.Json.Serialization
Imports System.Collections.Generic
Public Class DeepStatusClient
Private ReadOnly _httpClient As HttpClient
Private ReadOnly _baseUrl As String = "https://your-api-domain.com"
Public Sub New()
_httpClient = New HttpClient()
_httpClient.BaseAddress = New Uri(_baseUrl)
' Longer timeout for deep checks (2-5 seconds expected)
_httpClient.Timeout = TimeSpan.FromSeconds(30)
End Sub
Public Async Function CheckDeepStatusAsync() As Task(Of DependencyCheckResponse)
Try
' Make the GET request (no authentication required)
Dim response As HttpResponseMessage = Await _httpClient.GetAsync("/v1/rest/status/deep")
Dim responseBody As String = Await response.Content.ReadAsStringAsync()
Dim options As New JsonSerializerOptions()
options.PropertyNameCaseInsensitive = True
Dim result As DependencyCheckResponse = JsonSerializer.Deserialize(Of DependencyCheckResponse)(responseBody, options)
' HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
If response.IsSuccessStatusCode Then
Console.WriteLine("All dependencies passed deep health checks.")
ElseIf CInt(response.StatusCode) = 503 Then
Console.WriteLine("One or more dependencies failed deep health checks:")
For Each dep In result.Dependencies
If dep.Status <> "Healthy" Then
Console.WriteLine($" - {dep.Name}: {dep.Status}")
Console.WriteLine($" Message: {dep.Message}")
End If
Next
End If
Return result
Catch ex As TaskCanceledException
Console.WriteLine("Deep status check timed out. The service may be under heavy load.")
Throw
Catch ex As Exception
Console.WriteLine($"Deep status check failed: {ex.Message}")
Throw
End Try
End Function
End Class
Public Class DependencyCheckResponse
Public Property Status As String
Public Property Dependencies As List(Of DependencyStatus)
End Class
Public Class DependencyStatus
Public Property Name As String
Public Property Status As String
Public Property Message As String
End Class
' Example usage:
Dim client As New DeepStatusClient()
Dim statusResponse As DependencyCheckResponse = Await client.CheckDeepStatusAsync()
Console.WriteLine($"Overall Status: {statusResponse.Status}")
Console.WriteLine("Dependency Details:")
For Each dep In statusResponse.Dependencies
Dim indicator As String = If(dep.Status = "Healthy", "[OK]", "[FAIL]")
Console.WriteLine($" {indicator} {dep.Name}: {dep.Status} - {dep.Message}")
Next
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.List;
public class DeepStatusClient {
private final HttpClient httpClient;
private final String baseUrl;
private final ObjectMapper objectMapper;
public DeepStatusClient() {
this.baseUrl = "https://your-api-domain.com";
this.httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(30))
.build();
this.objectMapper = new ObjectMapper();
}
public DependencyCheckResponse checkDeepStatus() throws Exception {
// Construct the endpoint URL
String endpoint = baseUrl + "/v1/rest/status/deep";
// Build the HTTP request (no authentication required)
// Use a longer timeout for deep checks (2-5 seconds expected)
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(endpoint))
.timeout(Duration.ofSeconds(30))
.GET()
.build();
// Send the request and get response
HttpResponse<String> response = httpClient.send(
request,
HttpResponse.BodyHandlers.ofString()
);
DependencyCheckResponse result = objectMapper.readValue(
response.body(),
DependencyCheckResponse.class
);
// HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
if (response.statusCode() == 200) {
System.out.println("All dependencies passed deep health checks.");
} else if (response.statusCode() == 503) {
System.out.println("One or more dependencies failed deep health checks:");
for (DependencyStatus dep : result.dependencies) {
if (!"Healthy".equals(dep.status)) {
System.out.println(" - " + dep.name + ": " + dep.status);
System.out.println(" Message: " + dep.message);
}
}
} else {
throw new Exception("Unexpected status code: " + response.statusCode());
}
return result;
}
public static class DependencyCheckResponse {
public String status;
public List<DependencyStatus> dependencies;
}
public static class DependencyStatus {
public String name;
public String status;
public String message;
}
// Example usage
public static void main(String[] args) {
try {
DeepStatusClient client = new DeepStatusClient();
DependencyCheckResponse result = client.checkDeepStatus();
System.out.println("Overall Status: " + result.status);
System.out.println("Dependency Details:");
for (DependencyStatus dep : result.dependencies) {
String indicator = "Healthy".equals(dep.status) ? "[OK]" : "[FAIL]";
System.out.println(" " + indicator + " " + dep.name + ": " + dep.status + " - " + dep.message);
}
} catch (Exception e) {
System.out.println("Deep status check failed: " + e.getMessage());
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
require 'timeout'
class DeepStatusClient
def initialize
@base_url = 'https://your-api-domain.com'
end
def check_deep_status
# Construct the endpoint URL
uri = URI("#{@base_url}/v1/rest/status/deep")
# Create the HTTP request (no authentication required)
request = Net::HTTP::Get.new(uri)
# Send the request with a longer timeout for deep checks (2-5 seconds expected)
response = Timeout.timeout(30) do
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.read_timeout = 30
http.request(request)
end
end
result = JSON.parse(response.body)
# HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
case response.code.to_i
when 200
puts 'All dependencies passed deep health checks.'
when 503
puts 'One or more dependencies failed deep health checks:'
result['dependencies']&.each do |dep|
unless dep['status'] == 'Healthy'
puts " - #{dep['name']}: #{dep['status']}"
puts " Message: #{dep['message']}"
end
end
else
raise "Unexpected status code: #{response.code}"
end
result
rescue Timeout::Error
puts 'Deep status check timed out. The service may be under heavy load.'
raise
rescue StandardError => e
puts "Deep status check failed: #{e.message}"
raise
end
end
# Example usage:
client = DeepStatusClient.new
result = client.check_deep_status
puts "Overall Status: #{result['status']}"
puts 'Dependency Details:'
result['dependencies']&.each do |dep|
indicator = dep['status'] == 'Healthy' ? '[OK]' : '[FAIL]'
puts " #{indicator} #{dep['name']}: #{dep['status']} - #{dep['message']}"
end
Response Format
Success Response (200 OK) - All Dependencies Healthy
{
"status": "Healthy",
"dependencies": [
{
"name": "TransIT Gateway",
"status": "Healthy",
"message": "Full health check passed - transaction processing operational"
},
{
"name": "Database",
"status": "Healthy",
"message": "Full health check passed - read/write operations verified"
},
{
"name": "AWS Cognito",
"status": "Healthy",
"message": "Full health check passed - authentication service operational"
},
{
"name": "Cache Service",
"status": "Healthy",
"message": "Full health check passed - cache read/write operations verified"
}
]
}
Service Unavailable Response (503) - One or More Dependencies Unhealthy
{
"status": "Unhealthy",
"dependencies": [
{
"name": "TransIT Gateway",
"status": "Healthy",
"message": "Full health check passed - transaction processing operational"
},
{
"name": "Database",
"status": "Unhealthy",
"message": "Health check failed - read operation timed out after 5000ms"
},
{
"name": "AWS Cognito",
"status": "Healthy",
"message": "Full health check passed - authentication service operational"
},
{
"name": "Cache Service",
"status": "Unhealthy",
"message": "Health check failed - write operation returned error: connection refused"
}
]
}
Error Response (500 Internal Server Error)
{
"status": "Unhealthy",
"responseStatus": "Error",
"responseMessage": "An unexpected error occurred while performing deep health checks",
"correlationId": "abc123-def456-ghi789"
}
Response Fields
| Field | Type | Description |
|---|---|---|
status |
string | Overall status - "Healthy" if all dependencies pass deep checks, "Unhealthy" if any dependency fails |
dependencies |
array | Array of dependency status objects detailing each downstream service's full health check result |
dependencies[].name |
string | Name of the downstream dependency (e.g., "TransIT Gateway", "Database") |
dependencies[].status |
string | Dependency status - "Healthy" or "Unhealthy" |
dependencies[].message |
string | Detailed message describing the full health check result, including specific operations verified or error details |
responseStatus |
string | (Error responses only) Status indicator |
responseMessage |
string | (Error responses only) Human-readable error message |
correlationId |
string | (Error responses only) Correlation ID for support tracking |
Shallow vs. Deep Checks
Understanding the difference between shallow and deep checks is important for choosing the right endpoint:
| Aspect | Shallow Check | Deep Check |
|---|---|---|
| What it tests | Token-only connectivity (can the service reach the dependency?) | Full operational health (can the dependency perform its actual functions?) |
| Response time | ~500ms | ~2-5 seconds |
| Performance impact | Minimal | Moderate - performs actual operations on dependencies |
| Suitable for automation | Yes - safe for frequent polling (every 1-5 minutes) | No - use sparingly (manual or infrequent scheduled checks) |
| Failure detection | Detects connectivity failures and complete outages | Detects connectivity failures, partial degradation, and functional errors |
Common Use Cases
1. Detailed Diagnostics
Investigate dependency health when issues are suspected:
- Use when the shallow check reports an unhealthy dependency
- Get specific details about what operations are failing
- Identify partial degradation that shallow checks cannot detect
- Provide detailed health reports to operations teams
2. Troubleshooting and Incident Response
Diagnose issues during active incidents:
- Run a deep check to determine the exact state of each dependency
- Use the detailed messages to identify root causes
- Correlate dependency failures with application errors
- Document dependency health state for incident reports
3. Post-Deployment Validation
Confirm full system health after changes:
- Run a deep check after deploying new service versions
- Verify that configuration changes have not broken dependency connectivity
- Confirm that all dependencies are fully operational before routing traffic
- Include in deployment runbooks as a validation step
4. Scheduled Health Reports
Generate periodic comprehensive health reports:
- Schedule deep checks once per hour or less frequently
- Store results for historical health trend analysis
- Generate SLA compliance reports based on deep check results
- Compare deep check results over time to identify degradation patterns
Comparison with Other Status Endpoints
| Endpoint | Check Type | Response Time | Dependencies Detail | Use Case |
|---|---|---|---|---|
| /status | Simple liveness | ~100ms | None | Load balancer health checks, uptime monitoring |
| /status/shallow | Token-only dependency check | ~500ms | Per-dependency connectivity | Quick dependency connectivity verification, automated monitoring |
| /status/deep | Full dependency health check | ~2-5s | Full operational health | Detailed diagnostics, manual troubleshooting, post-deployment validation |
Additional Notes
- No Authentication: This endpoint intentionally does not require authentication for easier operations access during incident response.
- Full Health Checks: Unlike the shallow check, the deep check exercises actual operations on each dependency (e.g., database read/write, gateway connectivity tests).
- Longer Response Time: Expect 2-5 seconds for a complete response. Set client-side timeouts of at least 30 seconds to account for slow dependencies.
- Performance Impact: Deep checks perform real operations on dependencies. Do not use this endpoint for frequent automated polling, as it can add unnecessary load to downstream services.
- HTTP Status Codes: Returns HTTP 200 when all dependencies pass deep checks, HTTP 503 when one or more fail, and HTTP 500 for unexpected errors.
- The
dependenciesarray always includes all monitored downstream services, regardless of their individual status. - The
messagefield provides detailed context about what was tested and the specific result or error encountered. - For routine monitoring, prefer the Shallow Status endpoint. Reserve deep checks for diagnostics and troubleshooting.
- A dependency that passes shallow checks but fails deep checks may have partial functionality issues (e.g., read-only mode, degraded performance).
Troubleshooting
503 Service Unavailable
- One or more dependencies failed their full health check
- Inspect the
dependenciesarray to identify which specific dependencies are unhealthy - Review the
messagefield for each unhealthy dependency to understand the specific failure - Check whether the dependency is experiencing a known outage or maintenance window
- Verify network connectivity between the Integration Service and the failing dependency
500 Internal Server Error
- The service experienced an unexpected error while performing deep health checks
- Check the
correlationIdin the response for support tracking - Alert your operations team immediately
- Check service logs for detailed error information
Timeout / No Response
- Deep checks take 2-5 seconds normally; ensure your client timeout is at least 30 seconds
- If the check times out, the service may be under severe load or a dependency check is hanging
- Try the Shallow Status endpoint first to quickly identify unreachable dependencies
- Check DNS resolution for the API domain
- Verify firewall rules allow outbound HTTPS traffic
Dependency Passes Shallow but Fails Deep
- The dependency is reachable but not fully operational
- Common causes: database in read-only mode, gateway rejecting operations, cache returning stale data
- Review the
messagefield for the specific operation that failed - Contact the dependency team or vendor with the specific error details
- Contact Procare Pay support if the issue persists and appears to be on the Integration Service side
Intermittent Failures
- If a dependency shows "Unhealthy" intermittently, it may be experiencing load-related issues
- Run the deep check 2-3 times in succession to confirm the failure is persistent
- Compare with shallow check results to determine if the issue is connectivity or functionality
- Contact support with the correlation IDs from multiple failed checks for investigation