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:

Valid request header values for OpenAPI v2 queries
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.
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.
Stable level
- The version name is vX where X is an integer.
- Stable versions of features will appear in released software for many subsequent versions.

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 uses apiVersion: v1.
The Named groups are at REST path /apis/$GROUP_NAME/$VERSION, and use apiVersion: $GROUP_NAME/$VERSION (e.g. apiVersion: batch/v1).