Get Simple Service Status
GET
/v1/rest/status
Description: Returns a simple liveness status indicating whether the Integration Service API is up and running. This endpoint performs a lightweight token-only connectivity check against all downstream dependencies.
What is this endpoint used for?
This endpoint provides a quick health check for monitoring and operations:
- Service Availability: Verify the API is accessible and responding
- Load Balancer Health Checks: Configure as a health check endpoint for load balancers
- Monitoring Systems: Integrate with monitoring tools like Pingdom, DataDog, or New Relic
- Uptime Tracking: Monitor service uptime and availability
- Quick Diagnostics: Get a fast status check without detailed dependency information
No Authentication Required: This endpoint does NOT require authentication, making it suitable for public health checks and monitoring systems.
Code Examples
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text.Json;
public class StatusClient
{
private readonly HttpClient _httpClient;
private readonly string _baseUrl = "https://your-api-domain.com";
public StatusClient()
{
_httpClient = new HttpClient();
_httpClient.BaseAddress = new Uri(_baseUrl);
_httpClient.Timeout = TimeSpan.FromSeconds(5); // Short timeout for health checks
}
public async Task<bool> CheckServiceStatusAsync()
{
try
{
// Make the GET request (no authentication required)
var response = await _httpClient.GetAsync("/v1/rest/status");
// Check response status
if (response.IsSuccessStatusCode)
{
var responseBody = await response.Content.ReadAsStringAsync();
var status = JsonSerializer.Deserialize<StatusResponse>(responseBody);
return status.Status.Equals("Up", StringComparison.OrdinalIgnoreCase);
}
else
{
Console.WriteLine($"Service returned status code: {response.StatusCode}");
return false;
}
}
catch (Exception ex)
{
Console.WriteLine($"Health check failed: {ex.Message}");
return false;
}
}
}
public class StatusResponse
{
public string Status { get; set; }
}
// Example usage:
var statusClient = new StatusClient();
bool isServiceUp = await statusClient.CheckServiceStatusAsync();
if (isServiceUp)
{
Console.WriteLine("✓ Service is UP and healthy");
}
else
{
Console.WriteLine("✗ Service is DOWN or unhealthy");
}
Imports System.Net.Http
Imports System.Text.Json
Public Class StatusClient
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(5) ' Short timeout for health checks
End Sub
Public Async Function CheckServiceStatusAsync() As Task(Of Boolean)
Try
' Make the GET request (no authentication required)
Dim response As HttpResponseMessage = Await _httpClient.GetAsync("/v1/rest/status")
' Check response status
If response.IsSuccessStatusCode Then
Dim responseBody As String = Await response.Content.ReadAsStringAsync()
Dim statusObj As StatusResponse = JsonSerializer.Deserialize(Of StatusResponse)(responseBody)
Return statusObj.Status.Equals("Up", StringComparison.OrdinalIgnoreCase)
Else
Console.WriteLine($"Service returned status code: {response.StatusCode}")
Return False
End If
Catch ex As Exception
Console.WriteLine($"Health check failed: {ex.Message}")
Return False
End Try
End Function
End Class
Public Class StatusResponse
Public Property Status As String
End Class
' Example usage:
Dim statusClient As New StatusClient()
Dim isServiceUp As Boolean = Await statusClient.CheckServiceStatusAsync()
If isServiceUp Then
Console.WriteLine("✓ Service is UP and healthy")
Else
Console.WriteLine("✗ Service is DOWN or unhealthy")
End If
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;
public class StatusClient {
private final HttpClient httpClient;
private final String baseUrl;
private final ObjectMapper objectMapper;
public StatusClient() {
this.baseUrl = "https://your-api-domain.com";
this.httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(5))
.build();
this.objectMapper = new ObjectMapper();
}
public boolean checkServiceStatus() {
try {
// Construct the endpoint URL
String endpoint = baseUrl + "/v1/rest/status";
// Build the HTTP request (no authentication required)
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(endpoint))
.timeout(Duration.ofSeconds(5))
.GET()
.build();
// Send the request and get response
HttpResponse<String> response = httpClient.send(
request,
HttpResponse.BodyHandlers.ofString()
);
// Check response status
if (response.statusCode() == 200) {
StatusResponse status = objectMapper.readValue(
response.body(),
StatusResponse.class
);
return "Up".equalsIgnoreCase(status.status);
} else {
System.out.println("Service returned status code: " + response.statusCode());
return false;
}
} catch (Exception e) {
System.out.println("Health check failed: " + e.getMessage());
return false;
}
}
public static class StatusResponse {
public String status;
}
// Example usage
public static void main(String[] args) {
StatusClient client = new StatusClient();
boolean isServiceUp = client.checkServiceStatus();
if (isServiceUp) {
System.out.println("✓ Service is UP and healthy");
} else {
System.out.println("✗ Service is DOWN or unhealthy");
}
}
}
require 'net/http'
require 'uri'
require 'json'
require 'timeout'
class StatusClient
def initialize
@base_url = 'https://your-api-domain.com'
end
def check_service_status
# Construct the endpoint URL
uri = URI("#{@base_url}/v1/rest/status")
# Create the HTTP request (no authentication required)
request = Net::HTTP::Get.new(uri)
# Send the request with timeout
begin
response = Timeout.timeout(5) do
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
end
# Check response status
if response.is_a?(Net::HTTPSuccess)
result = JSON.parse(response.body)
result['status']&.downcase == 'up'
else
puts "Service returned status code: #{response.code}"
false
end
rescue StandardError => e
puts "Health check failed: #{e.message}"
false
end
end
end
# Example usage:
client = StatusClient.new
is_service_up = client.check_service_status
if is_service_up
puts "✓ Service is UP and healthy"
else
puts "✗ Service is DOWN or unhealthy"
end
Response Format
Success Response (200 OK)
{
"status": "Up"
}
Error Response (500 Internal Server Error)
{
"status": "Down",
"responseStatus": "Error",
"responseMessage": "Service is experiencing issues",
"correlationId": "abc123-def456-ghi789"
}
Response Fields
| Field | Type | Description |
|---|---|---|
status |
string | Service status - either "Up" or "Down" |
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. Load Balancer Health Checks
Configure this endpoint as a health check target:
- Set as the health check URL in AWS ELB, ALB, or NLB
- Configure with a 5-second timeout
- Expect HTTP 200 status code for healthy instances
- Set health check interval to 30 seconds
2. Monitoring and Alerting
Integrate with monitoring systems:
- Poll this endpoint every 1-5 minutes from your monitoring tool
- Trigger alerts if status returns "Down" or HTTP 500
- Track uptime percentage over time
- Create dashboards showing service availability
3. Circuit Breaker Pattern
Implement circuit breakers in your application:
- Check status before making expensive API calls
- Open circuit if service returns "Down"
- Avoid cascading failures in distributed systems
- Implement exponential backoff for retries
4. Pre-Flight Checks
Verify service availability before critical operations:
- Check status before processing batch payments
- Validate service health during application startup
- Ensure connectivity before scheduled jobs
Additional Notes
- No Authentication: This endpoint intentionally does not require authentication for easier monitoring setup.
- Lightweight Check: This performs only a token-only connectivity check to dependencies, not a full health verification.
- Fast Response: Designed to respond quickly (typically under 500ms) for timely health assessments.
- Load Balancer Safe: Can be called frequently without impacting service performance.
- A "Up" status indicates the service is running but does NOT guarantee all dependencies are fully operational.
- For detailed dependency health information, use the Shallow Status or Deep Status endpoints.
- This endpoint returns HTTP 200 even when dependencies have issues (status: "Up" with warnings in other endpoints).
- HTTP 500 responses indicate the service itself is experiencing critical issues.
Comparison with Other Status Endpoints
| Endpoint | Check Type | Response Time | Use Case |
|---|---|---|---|
| /status | Simple liveness | ~100ms | Load balancer health checks, uptime monitoring |
| /status/shallow | Token-only dependency check | ~500ms | Quick dependency connectivity verification |
| /status/deep | Full dependency health check | ~2-5s | Detailed diagnostics, manual troubleshooting |
Troubleshooting
500 Internal Server Error
- The service is experiencing critical issues
- 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
- Service is completely unavailable or experiencing severe load
- Check DNS resolution for the API domain
- Verify firewall rules allow outbound HTTPS traffic
Status Returns "Down"
- Service is running but one or more critical dependencies are unavailable
- Check Shallow Status for dependency details
- Wait for automatic recovery (usually 1-5 minutes)
- Contact support if issue persists beyond 10 minutes