Built-in Endpoints¶

Apiary includes several built-in endpoints for health checks, metrics, authentication, and endpoint discovery.

Configuring Built-in Endpoints¶

Built-in endpoints can be selectively enabled or disabled in config/settings.json:

{
  "enable_landing_page": true,
  "enabled_routers": ["health", "metrics", "auth", "endpoints"]
}

Available routers:

health - Health check endpoints (/health, /health/live, /health/ready)
metrics - Application metrics endpoint (/metrics)
auth - Authentication endpoints (/auth/validate, /auth/status)
endpoints - Endpoint discovery (/endpoints)

Security Considerations¶

Information Disclosure Risk

Built-in endpoints can expose sensitive information about your API's internal structure, dependencies, usage patterns, and available services. Consider your security requirements when deploying to production.

What each endpoint reveals:

/metrics - Request counts, error rates, endpoint usage statistics
/endpoints - All configured endpoints and available services
/health/ready - Application version, uptime, dependency health status
/auth/validate - Can be used to test for valid API keys
/docs, /redoc, /openapi.json - Complete API schema, all endpoints, request/response formats

Production recommendations:

Disable all if you don't need them:
```
{
  "enabled_routers": []
}
```
Keep health checks only for Kubernetes/Docker deployments:
```
{
  "enabled_routers": ["health"]
}
```

You can also configure via environment variables:

ENABLED_ROUTERS='["health"]'  # JSON array as string
ENABLE_LANDING_PAGE=false

Health Check Endpoints¶

Basic Health Check¶

Endpoint: GET /health

Simple health check that returns the service status.

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Liveness Probe¶

Endpoint: GET /health/live

Kubernetes-compatible liveness probe. Returns 200 if the application is running.

curl http://localhost:8000/health/live

Response:

{
  "status": "alive"
}

Readiness Probe¶

Endpoint: GET /health/ready

Kubernetes-compatible readiness probe. Checks configuration validity and reports registered services.

curl http://localhost:8000/health/ready

Response (healthy):

{
  "status": "ready",
  "version": "0.1.1",
  "uptime_seconds": 3600,
  "dependencies": {
    "configuration": {
      "status": "healthy"
    },
    "services": {
      "status": "healthy",
      "registered": ["crypto", "hello"],
      "count": 2
    }
  }
}

Response (unready):

{
  "status": "unready",
  "version": "0.1.1",
  "uptime_seconds": 3600,
  "dependencies": {
    "configuration": {
      "status": "unhealthy",
      "error": "..."
    },
    "services": {
      "status": "healthy",
      "registered": [],
      "count": 0
    }
  }
}

Metrics Endpoint¶

Endpoint: GET /metrics

Returns application metrics including request counts, error rates, and endpoint statistics.

curl http://localhost:8000/metrics

Response:

{
  "total_requests": 1234,
  "total_errors": 5,
  "error_rate": 0.004,
  "endpoints": {
    "/api/crypto": {
      "count": 456,
      "avg_duration_ms": 123.45,
      "errors": 2
    }
  },
  "uptime_seconds": 86400
}

Authentication Endpoints¶

Validate API Key¶

Endpoint: GET /auth/validate

Validates an API key without requiring authentication.

# Without key
curl http://localhost:8000/auth/validate

# With key
curl -H "X-API-Key: your-key" http://localhost:8000/auth/validate

Response:

{
  "authenticated": true,
  "valid": true
}

Authentication Status¶

Endpoint: GET /auth/status

Requires authentication¶

Returns the current authentication status.

curl -H "X-API-Key: your-key" http://localhost:8000/auth/status

Response:

{
  "authenticated": true,
  "api_key": "your-key"
}

Endpoint Discovery¶

Endpoint: GET /endpoints

Lists all configurable endpoints and available services.

curl http://localhost:8000/endpoints

Response includes:

All configured endpoints from config/endpoints.json
Their status (enabled/disabled)
Authentication requirements
Available services
Tags and descriptions

Response:

{
  "endpoints": [
    {
      "path": "/api/crypto",
      "method": "GET",
      "service": "crypto",
      "enabled": true,
      "requires_auth": false,
      "description": "Get cryptocurrency price data"
    }
  ],
  "services": ["crypto", "weather"],
  "total": 1
}

API Documentation¶

Swagger UI¶

Endpoint: GET /docs

Interactive API documentation with Swagger UI.

Visit: http://localhost:8000/docs

Can be disabled in config/settings.json:

{
  "enable_docs": false
}

ReDoc¶

Endpoint: GET /redoc

Alternative API documentation with ReDoc.

Visit: http://localhost:8000/redoc

Can be disabled in config/settings.json:

{
  "enable_redoc": false
}

OpenAPI JSON¶

Endpoint: GET /openapi.json

Raw OpenAPI specification in JSON format.

curl http://localhost:8000/openapi.json

Can be disabled in config/settings.json:

{
  "enable_openapi": false
}

Disabling All Documentation

For production deployments, consider disabling all documentation endpoints to prevent information disclosure:

{
  "enable_docs": false,
  "enable_redoc": false,
  "enable_openapi": false
}

You can also use environment variables:

ENABLE_DOCS=false
ENABLE_REDOC=false
ENABLE_OPENAPI=false

Landing Page¶

Endpoint: GET /

HTML landing page (if enabled in settings).

Visit: http://localhost:8000/

Can be disabled in config/settings.json:

{
  "enable_landing_page": false
}

Rate Limiting Headers¶

All endpoints include rate limiting headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1234567890

Using Built-in Endpoints¶

Health Checks in Kubernetes¶

livenessProbe:
  httpGet:
    path: /health/live
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

Monitoring with Prometheus¶

Configure Prometheus to scrape /metrics:

scrape_configs:
  - job_name: 'apiary'
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: '/metrics'

CI/CD Health Checks¶

#!/bin/bash
# Wait for service to be ready
until curl -f http://localhost:8000/health/ready; do
  echo "Waiting for service..."
  sleep 5
done
echo "Service is ready!"

Next Steps¶

Configuration - Configure endpoints
Monitoring - Set up monitoring
Deployment - Deploy to production