API Compatibility
Nirmata Control Hub provides two kinds of REST API:
| API | Base path | Versioning |
|---|---|---|
| Policies API v1 | /policies/api/v1 | Versioned. Stable within a major version. |
| Platform API (model-based) | /{service}/api | Unversioned. May change. |
Versioned APIs
The major version is part of the URL, for example /policies/api/v1. Within a major version, Nirmata only makes
backward-compatible changes, such as:
- Adding new endpoints.
- Adding optional query parameters or optional request body fields.
- Adding new fields to responses.
- Adding new values to fields that list a set of values, such as statuses or types.
Write clients that tolerate these changes. Ignore response fields you don’t recognize, and handle values you don’t recognize gracefully.
Changes that break existing clients ship in a new major version, for example /policies/api/v2. Breaking changes
include removing or renaming endpoints or fields, changing a field’s type, adding a required parameter, and changing
an endpoint’s default behavior. When a new major version is released, the previous version is deprecated before it is
removed, and deprecations are announced in the release notes.
Only endpoints documented in this reference are covered by these guarantees. Undocumented endpoints under a versioned path are internal or experimental and can change without notice.
Platform API
The model-based platform API (/{service}/api/...) is not versioned.
Nirmata strives to keep it compatible, but some changes may break existing integrations. For new integrations, use a
versioned API where one covers your use case.