Skip to main content
A newer release of this product is available.

Resources and collections

Contributors dmp-netapp
PDFs

The Astra Control REST API provides access to resource instances and collections of resource instances.

Note Conceptually a REST resource is similar to an object as defined with the object-oriented programming (OOP) languages and systems. Sometimes these terms are used interchangeably. But in general, "resource" is preferred when used in the context of the external REST API while "object" is used for the corresponding stateful instance data stored at the server.

Attributes of the Astra resources

The Astra Control REST API conforms to RESTful design principles. Each Astra resource instance is created based on a well-defined resource type. A set of resource instances of the same type is referred to as a collection. The API calls act on individual resources or collections of resources.

Resource types

The resource types included with the Astra Control REST API have the following characteristics:

  • Every resource type is defined using a schema (typically in JSON)

  • Every resource schema includes the resource type and version

  • Resource types are globally unique

Resource instances

Resource instances available through the Astra Control REST API have the following characteristics:

  • Resource instances are created based on a single resource type

  • The resource type is indicated using the Media Type value

  • Instances are composed of stateful data which is maintained by the Astra service

  • Each instance is accessible through a unique and long-lived URL

  • In cases where a resource instance can have more than one representation, different media types can be used to request the desired representation

Resource collections

Resource collections available through the Astra Control REST API have the following characteristics:

  • The set of resource instances of a single resource type is known as a collection

  • Collections of resources have a unique and long-lived URL

Instance identifiers

Every resource instance is assigned an identifier when it is created. This identifier is a 128-bit UUIDv4 value. The assigned UUIDv4 values are globally unique and immutable. After issuing an API call that creates a new instance, a URL with the associated id is returned to the caller in a Location header of the HTTP response. You can extract the identifier and use it on subsequent calls when referring to the resource instance.

Note The resource identifier is the primary key used for collections.

Common structure for Astra resources

Every Astra Control resource is defined using a common structure.

Common data

Every Astra resource contains the key-values shown in the following table.

Key Description

type

A globally unique resource type which is known as the resource type.

version

A version identifier which is known as the resource version.

id

A globally unique identifier which is known as the resource identifier.

metadata

A JSON object containing various information, including user and system labels.
Metadata object

The metadata JSON object included with each Astra resource contains the key-values shown in the following table.

Key Description

labels

JSON array of client-specified labels associated with the resource.

creationTimestamp

JSON string containing a timestamp indicating when the resource was created.

modificationTimestamp

JSON string containing an ISO-8601 formatted timestamp indicating when the resource was last altered.

createdBy

JSON string containing the UUIDv4 identifier of the user id that created the resource. If the resource was created by an internal system component and there is no UUID associated with the creating entity, the null UUID is used.
Resource state

Selected resources a state value which is used to orchestrate lifecycle transitions and control access.