API conventions

The declarative resource model shared by every Datum Cloud resource: apiVersion, kind, metadata, spec, and status.

Every Datum Cloud resource — a DNSZone, an HTTPRoute, a Project, a billing account — follows the same shape and the same workflow. Learn it once and it applies to everything in the API resource reference.

This page is the entry point for the API concepts. Once you understand the common shape here, follow the details: Object metadata, Status & conditions, and Scopes cover the three top-level sections, while Field formats & types, Resource references, Versioning & stability, and Validation & safe changes explain how fields are described, linked, versioned, and checked.

The Datum Cloud API is currently alpha (v1alpha1). Resources, fields, and defaults may change in backward-incompatible ways between releases. The Gateway API networking resources (for example HTTPRoute) are served at the stable v1 version.

The declarative model

Datum Cloud is declarative. You don’t issue step-by-step commands to build something. Instead, you write down the state you want a resource to be in, hand it to the platform, and the platform does the work of making reality match — and keeps it that way. This is the core idea behind every resource:

• You declare desired state (the spec).
• The platform reconciles continuously, taking whatever actions are needed to reach that state.
• The platform reports observed state (the status) so you can see what actually happened.

You describe the destination; the platform figures out the route and tells you where things stand.

The top-level shape

Every resource is an object with the same four top-level fields:

Field	Purpose	Who writes it
apiVersion	The API group and version the resource belongs to (<group>/<version>).	You
kind	The type of resource, for example DNSZone.	You
metadata	Identity and bookkeeping — the resource’s name, labels, annotations, and more.	You (mostly)
spec	The desired state — the fields you set to declare what you want.	You
status	The observed state — what the platform reports back. Read-only.	The platform

A useful way to read any resource: spec is the request, status is the receipt. You own everything in spec; the platform owns everything in status. Never edit status — it’s overwritten by the platform on every reconcile.

apiVersion and kind: the resource’s identity

A resource type is identified by three things — its group, version, and kind (often abbreviated GVK):

• Group namespaces related resources together, for example dns.networking.miloapis.com.
• Version tracks the maturity and shape of the API, for example v1alpha1.
• Kind is the specific type, for example DNSZone.

The apiVersion field combines group and version as <group>/<version>, and kind names the type. Together they tell the platform exactly which resource you mean:

apiVersion: dns.networking.miloapis.com/v1alpha1
kind: DNSZone

Every page in the API resource reference opens with an Identity table listing the group, version, kind, and scope for that resource. For example, DNSZone is served at group dns.networking.miloapis.com, version v1alpha1, kind DNSZone, scope Project.

metadata: naming and organizing

metadata carries the resource’s identity and bookkeeping fields — its name, any labels and annotations, and platform-managed values you’ll see on resources you read back. See Object metadata for the full breakdown.

spec: what you want

spec is where you declare desired state. The available fields differ by resource type — a DNSZone spec names the zone’s domain, an HTTPRoute spec describes routing rules — but the meaning is always the same: this is what I want to exist. Each resource page documents its spec fields, their types, and which are required.

status: what actually happened

status is populated by the platform to report observed state. It commonly includes a set of conditions — standardized readiness signals such as Accepted and Programmed — plus resource-specific observed values. Because reconciliation is continuous, status is your window into whether the platform has caught up to your spec and whether anything went wrong. See Status & conditions.

A generic manifest skeleton

Strip away the resource-specific fields and every manifest looks like this:

apiVersion: <group>/<version>   # e.g. dns.networking.miloapis.com/v1alpha1
kind: <Kind>                    # e.g. DNSZone
metadata:
  name: <name>                  # unique within its scope
  labels:                       # optional: your own key/value tags
    example.com/team: platform
spec:
  # desired state — the fields you set (resource-specific)
# status is written by the platform; you don't include it when applying

You write everything above status. When you read a resource back, the platform will have added a status block (and filled in some managed metadata).

The desired-state workflow

Working with any resource is the same loop, regardless of type:

1. Declare desired state

   Write a manifest with apiVersion, kind, metadata, and the spec you want. You only ever author these.

2. Apply it

   Submit the manifest. The platform stores your desired state and begins reconciling toward it. See Changing resources and Safe changes & declarative config.

3. The platform reconciles

   Controllers take whatever actions are needed to make reality match your spec, and keep doing so as conditions change. You don’t drive these steps.

4. Read the reported status

   Inspect status (especially its conditions) to confirm the resource is ready, or to see why it isn’t. See Reading resources.

Because state is declarative, re-applying the same manifest is safe: the platform compares your desired state against what exists and only changes what’s different. Keep your manifests in version control and treat them as the source of truth.

Working with resources from the CLI

The API resource reference tells you what fields a resource has. The datumctl guides tell you how to apply and read them — the mechanics are identical for every resource type:

• Reading resources — get and inspect resources and their status.
• Changing resources — apply, create, and edit desired state.
• Safe changes & declarative config — preview changes and manage manifests declaratively.
• Output formats & scripting — machine-readable output for automation.
• Contexts & scoping — target the right Project or the Platform.
• Discovering resources & schemas — list available resource types and explore their fields live.

Because scope (Project vs. Platform) determines where a resource lives and how you address it, read Scopes alongside Contexts & scoping.