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
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
All APIs share the same path structure, methods and parameters. The base path depends on the level of the resource.
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.
|GET||List all objects|
|GET||Get one object|
|PATCH||Patch a part of one object|
|PUT||Replace one object|
|DELETE||Delete one object|
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:
|All within an Org|
|All within a Project|
To filter objects by a Zone, either across all Projects or within a single Project,
you can use a
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
zone fields are available (where applicable).
_5# With curl_5curl -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_5rok get jobs --field-selector zone=shared-aws-eu-west-1
All resources contain a top-level
metadata object with the following fields.
_12metadata:_12org: string_12project: string_12name: string_12uid: string_12labels: map[string]string_12annotations: map[string]string_12resourceVersion: string_12creationTimestamp: RFC3339 string_12lastUpdatedTimestamp: string_12deletionTimestamp: nullable RFC3339 string_12finalizers: list[string]
For resources that exist in a physical Zone like Jobs, Artifacts and Savepoints,
zone field stores the name of the Zone.
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.
auth are two API Groups in Immerok Cloud.
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.
Common subresources are:
status, to restrict write access to
.statusfields to the Immerok Cloud system.
finalizers, to restrict write access to the
.metadata.finalizersfield to the Immerok Cloud system.
job/proxy, to proxy requests to the Flink UI.
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.
.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.
Default values are applied to objects during creation.
GETs of the resource will include the default values explicitly.
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
metadata.resourceVersion of the object,
409 Conflict response will be returned to indicate the update should be retried after apply the change
to the latest version.
- 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
See the REST API reference for a full reference of Immerok Cloud's public REST API.