- StreamNative Cloud
- Concepts
StreamNative Cloud API
The StreamNative Cloud API lets you query and manipulate the state of objects in StreamNative Cloud. Users and external components communicate with one another through the API server.
OpenAPI specifications
For details about the complete API, see OpenAPI.
The StreamNative Cloud API server serves an OpenAPI spec via the /openapi/v0
endpoint. You can request the response format using request headers as follows:
Header | Possible values | Notes |
---|---|---|
Accept-Encoding | gzip | not supplying this header is also acceptable |
Accept | application/[email protected]+protobuf | mainly for intra-cluster use |
application/json | default | |
* | serves application/json |
StreamNative Cloud implements an alternative Protobuf based serialization format for the API.
API versions
To easily eliminate fields or restructure resource representations, StreamNative Cloud supports multiple API versions, each at a different API path. Versioning is completed at the API level instead of at the resource or field level to ensure that the API presents a clear, consistent view of system resources and behavior, and to enable controlling access to end-of-life and/or experimental APIs.
Different API versions imply different levels of stability and support.
- Alpha level
- The version names contain
alpha
(e.g.v1alpha1
). - There might be some bugs in the Alpha version.
- Some features might not be supported in a later software release without notice.
- The API might change in incompatible ways in a later software release without notice.
- Recommended usage might be only available in short-lived testing cluster, due to increased risk of bugs and lack of long-term support.
- The version names contain
- Beta level
- The version names contain
beta
(e.g.v2beta3
). - The code is well tested. It is safe to enable the feature.
- The overall features might be supported constantly, though details might change.
- The schema and/or semantics of objects might change in incompatible ways in a subsequent beta or stable release. When this happens, instructions are provided for migrating to the next version. This might require deleting, editing, and re-creating API objects. The editing process might require some thought. This might require downtime for applications that rely on the feature.
- Recommendations might be mainly for only non-business-critical uses because of potential for incompatible changes in subsequent releases. Please do try our beta features and give feedback on them! Once they exit beta, it might not be practical for us to make more changes.
- The version names contain
- Stable level
- The version name is
vX
whereX
is an integer. - Stable versions of features will appear in released software for many subsequent versions.
- The version name is
API groups
The API group is specified in a REST path and in the apiVersion
field of a serialized object.
The following API groups in a cluster are available:
The core group, also referred to as the legacy group, is at the REST path
/api/v1
and usesapiVersion: v1
.The Named groups are at REST path
/apis/$GROUP_NAME/$VERSION
, and useapiVersion: $GROUP_NAME/$VERSION
(e.g.apiVersion: batch/v1
).