Reference

Version & System Endpoints


Overview

The Version and System endpoints provide information about the Orcher orchestrator that serves the REST API: which API versions are supported, how to migrate between them, whether a given client is compatible with the server, and runtime system status. All endpoints in this group are public and do not require authentication.

Version Information

Get Current Version Info

Returns an overview of all API versions, including which versions are currently supported, deprecated, or sunset.

Request

1
curl http://localhost:8080/api/v1/version

Response 200 OK

1
{
2
"currentVersion": "v1",
3
"latestVersion": "v1",
4
"supportedVersions": ["v1"],
5
"deprecatedVersions": [],
6
"sunsetVersions": [],
7
"documentationUrl": "https://docs.orcher.io/api",
8
"changelogUrl": "https://docs.orcher.io/changelog"
9
}
FieldTypeDescription
currentVersionstringThe current stable API version.
latestVersionstringThe latest API version, including beta releases.
supportedVersionsstring[]All actively supported version identifiers.
deprecatedVersionsobject[]Versions that are deprecated but still reachable.
sunsetVersionsstring[]Versions that have been fully retired.
documentationUrlstringLink to the API documentation.
changelogUrlstringLink to the API changelog.

Each entry in deprecatedVersions contains:

FieldTypeDescription
versionstringThe deprecated version identifier.
sunsetDatestringISO 8601 date when the version will be removed.
replacementVersionstringThe recommended replacement version.
messagestringHuman-readable deprecation notice.

Get Specific Version Info

Returns detailed information about a single API version.

Request

1
curl http://localhost:8080/api/v1/version/v1

Response 200 OK

1
{
2
"version": "v1",
3
"status": "stable",
4
"deprecated": false,
5
"sunset": false,
6
"deprecationInfo": null,
7
"documentation": "https://docs.orcher.io/api/v1"
8
}
FieldTypeDescription
versionstringVersion identifier.
statusstringLifecycle status: development, beta, stable, deprecated, or sunset.
deprecatedbooleanWhether the version is deprecated.
sunsetbooleanWhether the version has been retired.
deprecationInfoobject/nullPresent only for deprecated versions (contains sunsetDate, replacementVersion, message).
documentationstringLink to version-specific documentation.

Status Codes

StatusDescription
200Version info returned successfully.
404The requested version does not exist.

Get Migration Guide

Returns a migration guide between two API versions, including breaking changes, step-by-step instructions, and estimated effort.

Request

1
curl http://localhost:8080/api/v1/version/migration/v1/v2

Response 200 OK

1
{
2
"fromVersion": "v1",
3
"toVersion": "v2",
4
"breakingChanges": [
5
{
6
"area": "Authentication",
7
"description": "JWT format changed",
8
"impact": "Medium",
9
"mitigation": "Update JWT parsing logic"
10
}
11
],
12
"migrationSteps": [
13
"Update API base URL",
14
"Update authentication flow"
15
],
16
"estimatedEffort": "Medium",
17
"documentationUrl": "https://docs.orcher.io/api/migration/v1-to-v2"
18
}
FieldTypeDescription
fromVersionstringSource version.
toVersionstringTarget version.
breakingChangesobject[]List of breaking changes (see below).
migrationStepsstring[]Ordered list of migration actions.
estimatedEffortstringEstimated effort level for the migration.
documentationUrlstringLink to the full migration guide.

Each entry in breakingChanges contains:

FieldTypeDescription
areastringAffected area (e.g., Authentication).
descriptionstringWhat changed.
impactstringImpact level (e.g., Low, Medium, High).
mitigationstringRecommended action to address the change.

Status Codes

StatusDescription
200Migration guide returned successfully.
404One or both versions not found, or no guide exists.

Check Version Compatibility

Checks whether a given client API version is compatible with a given server API version.

Request

1
curl http://localhost:8080/api/v1/version/compatibility/v1/v1

Response 200 OK

1
{
2
"compatible": true,
3
"status": "FullyCompatible",
4
"clientVersion": "v1",
5
"serverVersion": "v1",
6
"message": "Client and server versions are identical",
7
"recommendation": "Consider upgrading to the latest version for new features"
8
}
FieldTypeDescription
compatiblebooleanWhether the client can communicate with the server.
statusstringOne of: FullyCompatible, BackwardCompatible, CompatibleWithWarning, Incompatible.
clientVersionstringThe client version that was checked.
serverVersionstringThe server version that was checked.
messagestringHuman-readable explanation.
recommendationstringSuggested next action, if any.

Status Codes

StatusDescription
200Compatibility result returned.
404One or both versions not found.

System Information

Get System Info

Returns general metadata about the running orchestrator, including the service name, build version, and uptime.

Request

1
curl http://localhost:8080/api/v1/system/info

Response 200 OK

1
{
2
"name": "<service name>",
3
"version": "0.1.0",
4
"uptime": "0d 0h 0m"
5
}
FieldTypeDescription
namestringThe service name.
versionstringThe build version from Cargo.toml.
uptimestringHow long the service has been running.

Get System Status

Returns the overall health status of the system and its individual components.

Request

1
curl http://localhost:8080/api/v1/system/status

Response 200 OK

1
{
2
"status": "healthy",
3
"components": [
4
{
5
"name": "<component>",
6
"status": "healthy"
7
}
8
]
9
}
FieldTypeDescription
statusstringOverall system status (e.g., healthy).
componentsobject[]Per-component status breakdown.

Each entry in components contains:

FieldTypeDescription
namestringComponent name.
statusstringComponent status (e.g., healthy, unknown, degraded).

Get Service Version

Returns the build version string of the running orchestrator.

Request

1
curl http://localhost:8080/api/v1/system/version

Response 200 OK

1
"0.1.0"

The response body is a plain JSON string containing the CARGO_PKG_VERSION of the orchestrator binary.

Get System Configuration

Returns the current non-sensitive system configuration. Sensitive values such as passwords and API keys are redacted.

Request

1
curl http://localhost:8080/api/v1/system/config

Response 200 OK

1
"configuration-placeholder"

Note: This endpoint currently returns a placeholder value. It will be expanded in a future release to expose sanitized runtime configuration.

Common Status Codes

All endpoints in this group may return the following status codes:

StatusDescription
200Request completed successfully.
404Requested resource not found.
500Internal server error.

Next Steps

  • API Overview -- Introduction to the Orcher REST API and authentication.
  • Health & System -- Health check endpoints for readiness and liveness probes.
  • Errors & Limits -- Error response format and rate-limiting details.