API Concepts

The Immerok Cloud API follows many of Kubernetes' API concepts and conventions. In the following you will find a summary of these concepts in the context of Immerok Cloud.

API Hierarchy

Immerok Cloud's API resources are organized on three levels.

• Global resources are not attached to any parent resource. The only global resources are Orgs as the primary tenant.
• Org-scoped resources are global within an Org, such as Projects.
• Project-scoped resources are additionally scoped to a Project.

Names & References

For each resource kind, all objects have unique names within their level. For example, Artifacts, Jobs, and Savepoints within the same Project, or Projects within their Org. This means that an Artifact and a Job, within the same Project, may have the same name, or two Jobs in different Projects may have the same name, but two Jobs within the same Project cannot have the same name. This allows idempotent creation and updating of objects.

Objects reference other objects by name. For example, a Job references an Artifact by name via .spec.artifactRef.name. References between objects are resolved asynchronously, meaning that a referenced object doesn't need to exist before the referencing object is created. The reference will be checked at the time it is needed and retried indefinitely until it is resolved.

The only exception to this async reference resolution are references to the structural "parent" APIs. For example, a Project needs to exist before you can create objects in it.

Combined, these properties make Immerok Cloud's API declarative and, thus, easy to automate and integrate with.

Serving Resources over HTTP

Path Structure

All APIs share the same path structure, methods and parameters. The base path depends on the level of the resource.

Scoping	Base Path
Global	/apis/{group}/{version}/{resource}
Org-Scoped	/apis/{group}/{version}/orgs/{org}/{resource}/
Project-Scoped	/apis/{group}/{version}/orgs/{org}/projects/{project}/{resource}

Verbs

HTTP verbs correspond to logical actions to perform. Actions that operate on a single object require the name to identify it as the last section of the path, e.g. /{resource}/{name}.

HTTP Verb	Path	Action
GET	/{resource}	List all objects
GET	/{resource}/{name}	Get one object
PATCH	/{resource}/{name}	Patch a part of one object
PUT	/{resource}/{name}	Replace one object
DELETE	/{resource}/{name}	Delete one object

Listing

Often, you want to search across all objects within a Project.

For listing across projects HTTP GET endpoints are served at the correspondingly scoped path, independent of the API resource's scoping:

List...	Path
All within an Org	/apis/{group}/{version}/orgs/{org}/{resource}
All within a Project	/apis/{group}/{version}/orgs/{org}/projects/{project}/{resource}

To filter objects by a Zone, either across all Projects or within a single Project, you can use a fieldSelector.

Field Selectors

Field selectors are used to filter a collection of objects by their fields. Not all fields of an API are available for selection. By default, only metadata.name, metadata.project, and zone fields are available (where applicable).

_5

# With curl

_5

curl -X GET "https://api.immerok.cloud/apis/core/v1alpha1/orgs/my-org/projects/my-project/jobs?fieldSelector=shared-aws-eu-west-1"

_5

_5

# With the rok CLI

_5

rok get jobs --field-selector zone=shared-aws-eu-west-1

Common Metadata

All resources contain a top-level metadata object with the following fields.

_12

metadata:

_12

org: string

_12

project: string

_12

name: string

_12

uid: string

_12

labels: map[string]string

_12

annotations: map[string]string

_12

resourceVersion: string

_12

creationTimestamp: RFC3339 string

_12

lastUpdatedTimestamp: string

_12

deletionTimestamp: nullable RFC3339 string

_12

finalizers: list[string]

For resources that exist in a physical Zone like Jobs, Artifacts and Savepoints, the top-level zone field stores the name of the Zone.

_1

zone: string

API Groups & Versions

Immerok Cloud's APIs are semantically grouped into API Groups. An API Group is a set of resources that are exposed together. For example, core and auth are two API Groups in Immerok Cloud.

Subresources

When an API wants to either a) expose an operation that does not fit into the traditional REST pattern (i.e. CRUD), or b) restrict write access to a portion of the object, it can use a subresource to expose that functionality. Subresources are exposed at the end of the path, e.g. /{resource}/{name}/{subresource}.

Common subresources are:

• status, to restrict write access to .status fields to the Immerok Cloud system.
• finalizers, to restrict write access to the .metadata.finalizers field to the Immerok Cloud system.
• job/proxy, to proxy requests to the Flink UI.

Resource Deletion

When a resource is deleted, it is not immediately removed from the system. Instead, it is marked as "pending deletion" (via setting the .metadata.deletionTimestamp) and the system begins work to release all of its resources.

The .metadata.finalizers field is used to track which resources need to be released, and will be emptied during the process. Once all the resources are freed, the resource will be removed from the system.

Once the resource is removed, its name can be reused for a new resource.

Defaulting

Default values are applied to objects during creation. Subsequent GETs of the resource will include the default values explicitly.

Optimistic Updates

Like Kubernetes, the Immerok Cloud API doesn't have transactions. Rather, it uses optimistic locking to ensure that competing updates don't overwrite each other.

When an object is updated, the metadata.resourceVersion field is changed by the system. When an update is attempted, the metadata.resourceVersion field must match the current metadata.resourceVersion of the object, otherwise a 409 Conflict response will be returned to indicate the update should be retried after apply the change to the latest version.

Constraints

• Zone, Org, and Project names must be valid DNS labels according to RFC 1123 (i.e. [a-z0-9]([-a-z0-9]*[a-z0-9])?).
• All resource names must be valid DNS subdomains according to RFC 1123 (i.e., the regex above including dots).
• Annotations and labels each have a maximum total size of 256 KB, and their keys must be qualified names (e.g., example.com/Environment, team-a).

See Also

See the REST API reference for a full reference of Immerok Cloud's public REST API.