Get Shallow Dependency Status
GET
/v1/rest/status/shallow
Description: Returns the connectivity status of all downstream dependencies using token-only checks. This provides a quick assessment of whether the service can connect to its dependencies without performing deep health validations.
What is this endpoint used for?
This endpoint provides a fast dependency connectivity assessment for operations and monitoring:
- Quick Dependency Check: Verify that all downstream services are reachable and responding to basic requests
- Pre-Flight Validation: Confirm dependency connectivity before initiating critical operations such as batch payment processing
- Monitoring Dashboards: Integrate with monitoring tools to track dependency health over time
- Automated Alerting: Trigger alerts when one or more dependencies become unreachable
- Faster Than Deep Check: Completes in approximately 500ms compared to 2-5 seconds for the deep check
No Authentication Required: This endpoint does NOT require authentication, making it suitable for infrastructure monitoring, load balancer health checks, and external monitoring systems.
Token-Only Checks: This endpoint only verifies that the service can establish connectivity with each dependency. It does NOT perform full functional health checks. A dependency may appear "Healthy" in a shallow check but still have issues that would be detected by the Deep Status endpoint.
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 ShallowStatusClient
{
private readonly HttpClient _httpClient;
private readonly string _baseUrl = "https://your-api-domain.com";
public ShallowStatusClient()
{
_httpClient = new HttpClient();
_httpClient.BaseAddress = new Uri(_baseUrl);
_httpClient.Timeout = TimeSpan.FromSeconds(10);
}
public async Task<DependencyCheckResponse> CheckShallowStatusAsync()
{
try
{
// Make the GET request (no authentication required)
var response = await _httpClient.GetAsync("/v1/rest/status/shallow");
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 are healthy.");
}
else if ((int)response.StatusCode == 503)
{
Console.WriteLine("One or more dependencies are unhealthy:");
foreach (var dep in result.Dependencies)
{
if (dep.Status != "Healthy")
{
Console.WriteLine($" - {dep.Name}: {dep.Status} ({dep.Message})");
}
}
}
return result;
}
catch (Exception ex)
{
Console.WriteLine($"Shallow 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 ShallowStatusClient();
var statusResponse = await client.CheckShallowStatusAsync();
Console.WriteLine($"Overall Status: {statusResponse.Status}");
foreach (var dep in statusResponse.Dependencies)
{
Console.WriteLine($" {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 ShallowStatusClient
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)
_httpClient.Timeout = TimeSpan.FromSeconds(10)
End Sub
Public Async Function CheckShallowStatusAsync() As Task(Of DependencyCheckResponse)
Try
' Make the GET request (no authentication required)
Dim response As HttpResponseMessage = Await _httpClient.GetAsync("/v1/rest/status/shallow")
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 are healthy.")
ElseIf CInt(response.StatusCode) = 503 Then
Console.WriteLine("One or more dependencies are unhealthy:")
For Each dep In result.Dependencies
If dep.Status <> "Healthy" Then
Console.WriteLine($" - {dep.Name}: {dep.Status} ({dep.Message})")
End If
Next
End If
Return result
Catch ex As Exception
Console.WriteLine($"Shallow 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 ShallowStatusClient()
Dim statusResponse As DependencyCheckResponse = Await client.CheckShallowStatusAsync()
Console.WriteLine($"Overall Status: {statusResponse.Status}")
For Each dep In statusResponse.Dependencies
Console.WriteLine($" {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 ShallowStatusClient {
private final HttpClient httpClient;
private final String baseUrl;
private final ObjectMapper objectMapper;
public ShallowStatusClient() {
this.baseUrl = "https://your-api-domain.com";
this.httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
this.objectMapper = new ObjectMapper();
}
public DependencyCheckResponse checkShallowStatus() throws Exception {
// Construct the endpoint URL
String endpoint = baseUrl + "/v1/rest/status/shallow";
// Build the HTTP request (no authentication required)
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(endpoint))
.timeout(Duration.ofSeconds(10))
.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 are healthy.");
} else if (response.statusCode() == 503) {
System.out.println("One or more dependencies are unhealthy:");
for (DependencyStatus dep : result.dependencies) {
if (!"Healthy".equals(dep.status)) {
System.out.println(" - " + dep.name + ": " + dep.status + " (" + 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 {
ShallowStatusClient client = new ShallowStatusClient();
DependencyCheckResponse result = client.checkShallowStatus();
System.out.println("Overall Status: " + result.status);
for (DependencyStatus dep : result.dependencies) {
System.out.println(" " + dep.name + ": " + dep.status + " - " + dep.message);
}
} catch (Exception e) {
System.out.println("Shallow status check failed: " + e.getMessage());
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
require 'timeout'
class ShallowStatusClient
def initialize
@base_url = 'https://your-api-domain.com'
end
def check_shallow_status
# Construct the endpoint URL
uri = URI("#{@base_url}/v1/rest/status/shallow")
# Create the HTTP request (no authentication required)
request = Net::HTTP::Get.new(uri)
# Send the request with timeout
response = Timeout.timeout(10) do
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
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 are healthy.'
when 503
puts 'One or more dependencies are unhealthy:'
result['dependencies']&.each do |dep|
unless dep['status'] == 'Healthy'
puts " - #{dep['name']}: #{dep['status']} (#{dep['message']})"
end
end
else
raise "Unexpected status code: #{response.code}"
end
result
rescue StandardError => e
puts "Shallow status check failed: #{e.message}"
raise
end
end
# Example usage:
client = ShallowStatusClient.new
result = client.check_shallow_status
puts "Overall Status: #{result['status']}"
result['dependencies']&.each do |dep|
puts " #{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": "Connection established successfully"
},
{
"name": "Database",
"status": "Healthy",
"message": "Connection established successfully"
},
{
"name": "AWS Cognito",
"status": "Healthy",
"message": "Connection established successfully"
},
{
"name": "Cache Service",
"status": "Healthy",
"message": "Connection established successfully"
}
]
}
Service Unavailable Response (503) - One or More Dependencies Unhealthy
{
"status": "Unhealthy",
"dependencies": [
{
"name": "TransIT Gateway",
"status": "Healthy",
"message": "Connection established successfully"
},
{
"name": "Database",
"status": "Unhealthy",
"message": "Connection timed out after 5000ms"
},
{
"name": "AWS Cognito",
"status": "Healthy",
"message": "Connection established successfully"
},
{
"name": "Cache Service",
"status": "Healthy",
"message": "Connection established successfully"
}
]
}
Error Response (500 Internal Server Error)
{
"status": "Unhealthy",
"responseStatus": "Error",
"responseMessage": "An unexpected error occurred while checking dependency status",
"correlationId": "abc123-def456-ghi789"
}
Response Fields
| Field | Type | Description |
|---|---|---|
status |
string | Overall status - "Healthy" if all dependencies pass, "Unhealthy" if any dependency fails |
dependencies |
array | Array of dependency status objects detailing each downstream service |
dependencies[].name |
string | Name of the downstream dependency (e.g., "TransIT Gateway", "Database") |
dependencies[].status |
string | Dependency status - "Healthy" or "Unhealthy" |
dependencies[].message |
string | Human-readable message describing the check result 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 |
Common Use Cases
1. Quick Dependency Connectivity Check
Rapidly verify that all downstream services are reachable:
- Use as a pre-flight check before starting batch operations
- Verify connectivity after network changes or deployments
- Completes in approximately 500ms for fast feedback
- Suitable for automated checks running every 1-5 minutes
2. Monitoring and Alerting
Integrate with monitoring systems for dependency tracking:
- Poll this endpoint at regular intervals from monitoring tools
- Trigger alerts when any dependency transitions from "Healthy" to "Unhealthy"
- Track individual dependency health over time
- Build dashboards showing per-dependency availability
3. Pre-Flight Validation
Confirm dependency connectivity before critical operations:
- Check all dependencies before processing batch payments
- Validate connectivity during application startup
- Ensure all services are reachable before scheduled jobs
- Fail fast with specific dependency information rather than encountering errors mid-operation
4. Incident Response
Quickly identify which dependencies are affected during an outage:
- Run a shallow check to narrow down which dependency is unreachable
- Correlate dependency failures with application errors
- Follow up with the Deep Status endpoint for detailed diagnostics
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 |
Additional Notes
- No Authentication: This endpoint intentionally does not require authentication for easier infrastructure monitoring and operations tooling.
- Token-Only Checks: The shallow check verifies connectivity only. It confirms that each dependency is reachable but does not exercise full functionality.
- Fast Response: Designed to respond in approximately 500ms, making it suitable for frequent automated polling.
- HTTP Status Codes: Returns HTTP 200 when all dependencies are healthy, HTTP 503 when one or more are unhealthy, and HTTP 500 for unexpected errors.
- A "Healthy" result from the shallow check does NOT guarantee that dependencies are fully operational. Use the Deep Status endpoint for comprehensive validation.
- The
dependenciesarray always includes all monitored downstream services, regardless of their individual status. - The
messagefield provides human-readable context about each dependency's connectivity result. - This endpoint is safe to call frequently and has minimal performance impact on the service.
Troubleshooting
503 Service Unavailable
- One or more dependencies are unreachable or not responding
- Inspect the
dependenciesarray to identify which specific dependencies are unhealthy - Check network connectivity between the Integration Service and the failing dependency
- Verify that the dependency service is running and accepting connections
- For detailed diagnostics, follow up with the Deep Status endpoint
500 Internal Server Error
- The service experienced an unexpected error while performing the health check
- Check the
correlationIdin the response for support tracking - Alert your operations team immediately
- Check service logs for detailed error information
Timeout / No Response
- Network connectivity issues between your system and the API
- The service itself is completely unavailable or under severe load
- Check DNS resolution for the API domain
- Verify firewall rules allow outbound HTTPS traffic
- Consider setting a client-side timeout of 10 seconds for this endpoint
Individual Dependency Shows "Unhealthy"
- The specific dependency may be experiencing an outage or network partition
- Shallow checks verify connectivity only - the dependency process may be running but unreachable
- Wait 1-2 minutes and retry to rule out transient network issues
- Use the Deep Status endpoint for additional diagnostic detail
- Contact support if the issue persists beyond 10 minutes