AimableDocs
DocsAPI Reference

General

General

The General domain of the Aimable Platform API (v0.1.0) provides foundational endpoints for system health checks and version discovery. These endpoints are essential for monitoring, debugging, and ensuring compatibility across services in distributed environments. They are typically used by DevOps teams, platform administrators, and developers integrating with the Aimable ecosystem.

While these endpoints don’t manage business data, they are critical for operational visibility and service reliability. They help confirm API availability, verify deployment integrity, and support automated health checks in CI/CD pipelines or container orchestration platforms like Kubernetes.

Key Concepts

  • Health Check (/health, /v1/health): Lightweight endpoints that return 200 OK when the API is reachable and functioning. Used for liveness and readiness probes.
  • System Versions (/system/versions): Returns version information for all internal services. Useful for debugging, ensuring correct deployments, and tracking service-level compatibility.

These endpoints require no request body and return simple JSON responses. They are read-only and do not modify system state.

How to Use the Endpoints

1. Health Check (v0 and v1)

Check if the API is up and responding.

Endpoint:
GET /api-proxy/health
GET /api-proxy/v1/health

Example Request:

curl -X GET https://platform.aimable.com/api-proxy/health \
  -H "Authorization: Bearer <your-access-token>"

Response (200 OK):

{
  "status": "healthy",
  "message": "Service is operational"
}

✅ Tip: Use /health in load balancer health probes or container liveness checks.

2. Get System Versions

Retrieve deployed versions of all internal services.

Endpoint:
GET /api-proxy/system/versions

Example Request:

curl -X GET https://platform.aimable.com/api-proxy/system/versions \
  -H "Authorization: Bearer <your-access-token>"

Response (200 OK):

{
  "api_gateway": "v0.1.0",
  "user_service": "v0.2.3",
  "content_service": "v0.1.8",
  "auth_service": "v0.3.1",
  "timestamp": "2023-10-05T12:34:56Z"
}

🛠️ Use case: After a deployment, call this endpoint to verify that all services are running the expected versions.

Common Workflows

✅ Service Startup and Readiness

When deploying a client application or microservice that depends on Aimable Platform, follow this sequence:

  1. Check health to confirm connectivity:

    curl -s -o /dev/null -w "%{http_code}" https://platform.aimable.com/api-proxy/health

    If response is 200, proceed.

  2. Fetch system versions to validate environment:

    curl https://platform.aimable.com/api-proxy/system/versions \
  -H "Authorization: Bearer <token>"

    Confirm the versions match your integration requirements.

This workflow ensures your client is interacting with a live and correctly deployed platform.

🔄 Monitoring and Alerting

Set up automated health checks every 30–60 seconds using /health. If the endpoint returns anything other than 200, trigger alerts. Optionally, pair with /system/versions to detect unexpected rollbacks or version drift.

Authentication and Error Handling

Authentication

All General domain endpoints require authentication via a Bearer token:

Authorization: Bearer <your-access-token>

Tokens are issued through the Aimable identity system. Without a valid token, requests return 401 Unauthorized.

Error Responses

While these endpoints are designed to be stable, possible errors include:

  • 401 Unauthorized – Missing or invalid access token.
  • 503 Service Unavailable – The API is down or undergoing maintenance.

Example 401 Response:

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

⚠️ Note: These endpoints do not return detailed error information. A non-200 status typically indicates a critical system issue.

Summary

The General domain provides essential operational insights into the Aimable Platform API. Use /health for uptime monitoring and /system/versions for deployment validation. These endpoints are small but powerful tools for ensuring reliability and consistency in production environments.

Related Endpoints