Versioning
The Elastio API is versioned in the path, per service. Each operation’s path contains a version segment such as v1, v2 or v3, and different versions of the same resource can be live side by side. The OpenAPI document as a whole also carries a version (info.version), which is listed in the changelog.
Path versions
Section titled “Path versions”The version belongs to the service and the resource, not to the whole API. A new version of one resource doesn’t change the others, so a single integration commonly calls v1, v2 and v3 paths.
Published operations per prefix and version:
| Prefix | v1 |
v2 |
v3 |
|---|---|---|---|
/gateway/api/ |
122 | 50 | |
/gateway/shared-services/ |
70 | 13 | 98 |
/gateway/integration/ |
53 | 8 | |
/gateway/ingestion/ |
25 | ||
/gateway/reporting/ |
17 | 10 | |
/rbac/api/ |
37 | ||
/gateway/scans/ |
1 |
Two Cloud Configuration operations under /gateway/admin/posture/… have no version segment.
Some resources exist in more than one version. For example, policies are available at /gateway/shared-services/v1/policies, /v2/policies and /v3/policies, and alerts at /gateway/integration/v1/alerts and /v2/alerts. When you start a new integration, use the highest version that is published for the resource, and check the operation description in the API reference for differences.
Deprecations
Section titled “Deprecations”Deprecated operations are signalled in several places:
- The operation has
deprecated: truein the OpenAPI document. - The API reference and the endpoint cards in these docs label it Deprecated.
- It is listed, with its replacement, on Deprecations.
- Deprecations and removals are noted in the changelog for the spec release that introduces them.
A deprecated operation keeps working until it is removed. Retired operations may answer 410 Gone instead of being removed outright, as GET and PUT /gateway/shared-services/v3/system-events/subscriptions do today.
To catch deprecations early, regenerate your client from the OpenAPI document regularly, or check it in CI for deprecated: true on the operations you call.
Guidance for clients
Section titled “Guidance for clients”Within a published version, the API can gain new capabilities. Write clients that tolerate additive change:
- Ignore unknown fields. New fields can appear in responses. Don’t fail on fields you don’t recognize, and don’t use strict deserialization that rejects them.
- Don’t depend on field order in JSON objects, or on the order of items in a list unless you asked for a
sort_by. - Handle new enum values. A field such as
asset_kindorseveritycan gain values. Fall back to a sensible default instead of crashing. - Handle optional and
nullfields. A field can be omitted ornullwhen there is no value. - Don’t send fields you don’t need, and don’t rely on undocumented behavior or on the exact wording of error messages.
- Expect new operations, parameters and filters. New optional query parameters don’t change the behavior of requests that don’t use them.
- Pin to the OpenAPI document you tested with, and review the changelog before you upgrade.