API Status and Lifecycle

api_status_lifecycle.md

API Status and Lifecycle

Endpoint

Request

GET [service_api_root]/status

No authentication or custom accept header required.

Response

{
    "version": "1",
    "build": "1.2",
    "status": "active",
    "environment": "production",
    "nextMaintenanceWindow": {
        "begin": null,
        "end": null
    },
    "flags": ["basic-stuff", "cool-feature", "no-legacy-stuff"]
}

• version: high-level API version, only full-scale incompatible chances can increment this value.
• build: detailed API version, for minor compatible changes and new features.
• status: options:
  • active: working as expected.
  • maintenance: offline temporarily for maintenance.
  • deprecated: working, but new development on it is not recommented.
  • obsolete: only status endpoint working, functional endpoints only available in new version of API.
  • closed: only status endpoint working, service no longer available.
• environment: options:
  • development
  • test
  • uat
  • production
• nextMaintenanceWindow: begin and end date/time (ISO 8601 format) for the next scheduled maintenance window.
• flags: list of custom API-specific flags (usually features), defined as a string array. Convention: prefix disabled or unavailable features with "no-".

Client Behaviour Pseudocode

response = request GET "https://[service_api_root]/status"
if response.status_code == 200 Ok
    status = response.json
    if status.status == "active"
        if status.nextMaintenanceWindow.start
            display unobtrusive INFO dialog, informing status.nextMaintenanceWindow.start
        procceed to login or service home screen/page
    else if status.status == "maintenance"
        if app.can_work_offline
            display unobtrusive WARNING dialog, informing status.nextMaintenanceWindow.end
            procceed to login or service home screen/page
        else
            display undismissable WARNING dialog, informing status.nextMaintenanceWindow.end
            try to reconnect periodically
    else if status.status == "deprecated"
        if app.can_auto_update
            trigger auto_update
        else
            display modal WARNING dialog, asking to upgrade the app
        procceed to login or service home
    else if status.status == "obsolete"
        display undismissable ERROR dialog, asking to upgrade the app
    else if status.status == "closed"
        display undismissable ERROR dialog, informing service end-of-life
else if response.status_code == 426 Upgrade Required
    display undismissable ERROR dialog, asking to upgrade the app
else if response.status_code == 410 Gone
    display undismissable ERROR dialog, informing service end-of-life
else
    # All other status codes or connection timeout:
    if app.can_work_offline
        display unobtrusive WARNING dialog, informing that the system will be available soon
        procceed to login or service home screen/page
    else
        display modal ERROR dialog, informing that the system will be available soon
        try to reconnect after a while or trigged by the user