API compatibility
Build integrations that tolerate additive changes and preserve Openstead's public API guarantees.
The public core uses the /api/v1 prefix and is defined by the OpenAPI 3.1 specification. Its info.version records the contract revision. The current revision is 1.0.0.
Stable interfaces
Documented operation IDs identify operations consistently for generated clients. Breaking changes to a documented request requirement, response field type, authorization behavior, or resource meaning require a new major contract and migration path.
Additional endpoints, optional request fields, and additive response data can appear within the same major version.
Write forward-compatible clients
- Ignore response fields your application does not use.
- Tolerate unknown future status strings without treating them as success.
- Read the catalog for current choices and capabilities.
- Use UUIDs from responses, not resource names, in REST paths.
- Inspect envelopes and asynchronous state instead of assuming every 200 response means completed work.
- Use documented cursor and retry rules rather than inferring them from another endpoint.
Both official SDKs preserve additional response fields and tolerate future response status values. Polling helpers retain a deadline for unknown states.
Service configuration
Create and update accept the configuration fields defined in the specification. Unknown configuration keys are rejected. Constraints also depend on the service kind, plan, and current workspace entitlements.
PATCH merges supplied configuration values with existing ones. Omitting a field and explicitly clearing a nullable field are different operations. A service's kind cannot change in place.
Contract boundaries
The public core covers catalog, workspace reads, projects, services, variables, deployments, and logs. The dashboard and CLI may expose additional workflows with different contracts. An endpoint's presence in a browser network trace does not make it part of the supported core SDK interface.
SDK releases carry a copy of the specification used for their types. Pin an SDK version in your dependency lockfile, review release notes when upgrading, and validate the behavior your integration relies on.
Report an incompatibility
Contact Openstead support with the endpoint, HTTP method, returned request ID, SDK version, and a redacted example. Include the expected and observed behavior without credentials, secret values, or customer records.