Astra REST Implementation
Astra REST Implementation
Astra Automation
NetApp
December 04, 2023
Resources are the basic components of a web-based system. When creating a REST web services
application, early design tasks include:
Every system uses and maintains resources. A resource can be a file, business transaction, process, or
administrative entity. One of the first tasks in designing an application based on REST web services is to
identify the resources.
Resources are always in one of a finite number of states. The states, as well as the associated operations
used to affect the state changes, must be clearly defined.
URI endpoints
Every REST resource must be defined and made available using a well-defined addressing scheme. The
endpoints where the resources are located and identified use a Uniform Resource Identifier (URI). The URI
provides a general framework for creating a unique name for each resource in the network. The Uniform
Resource Locator (URL) is a type of URI used with web services to identify and access resources. Resources
are typically exposed in a hierarchical structure similar to a file directory.
HTTP messages
Hypertext Transfer Protocol (HTTP) is the protocol used by the web services client and server to exchange
request and response messages about the resources. As part of designing a web services application, HTTP
methods are mapped to the resources and corresponding state management actions. HTTP is stateless.
Therefore, to associate a set of related requests and responses as part of one transaction, additional
information must be included in the HTTP headers carried with the request and response data flows.
JSON formatting
While information can be structured and transferred between a web services client and server in several ways,
the most popular option is JavaScript Object Notation (JSON). JSON is an industry standard for representing
simple data structures in plain text and is used to transfer state information describing the resources. The Astra
1
Control REST API uses JSON to format the data carried in the body of each HTTP request and response.
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:
Resource instances
Resource instances available through the Astra Control REST API have the following characteristics:
Resource collections
Resource collections available through the Astra Control REST API have the following characteristics:
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.
2
Common structure for Astra resources
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.
creationTimest JSON string containing a timestamp indicating when the resource was created.
amp
modificationTi JSON string containing an ISO-8601 formatted timestamp indicating when the resource was
mestamp 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.
HTTP details
The Astra Control REST API uses HTTP and related parameters to act on the resource
instances and collections. Details of the HTTP implementation are presented below.
The Astra Control REST API implements a transactional model with well-defined operations and state
transitions.
3
operations include:
• Create
• Read
• Update
• Delete
For some of the Astra resources, only a subset of these operations is supported. You should review the Online
API reference for more information about a specific API call.
HTTP methods
The HTTP methods or verbs supported by the API are presented in the table below.
The following table summaries the HTTP headers used with the Astra Control REST API.
4
Header Type Usage notes
Location Response Contains the full URL of the newly created resource.
Query parameters
The following query parameters are available for use with resource collections. See Work with collections for
more information.
The HTTP status codes used by the Astra Control REST API are described below.
The Astra Control REST API also uses the Problem Details for HTTP APIs standard. See
Diagnostics and support for more information.
URL format
The general structure of the URL used to access a resource instance or collection
through the REST API is composed of several values. This structure reflects the
5
underlying object model and system design.
Account as the root
The root of the resource path to every REST endpoint is the Astra account. And so all paths in the URL begin
with /account/{account_id} where account_id is the unique UUIDv4 value for the account. Internally
structure this reflects a design where all resource access is based on a specific account.
• Core (/core)
• Managed application (/k8s)
• Topology (/topology)
Category version
Each of the three resource categories has a global version that controls the version of the resources accessed.
By convention and definition, moving to a new major version of a resource category (such as, from /v1 to /v2)
will introduce breaking changes in the API.
Example
• Resource path
• Complete URL
The format of the path and full URL used to access the Astra Control resources is based on
several values. See URL format for more information. Also see Online API reference for more
details about using the Astra resources and endpoints.
6
Summary of Astra Control REST resources
The primary resource endpoints provided in the Astra Control REST API are organized in three categories.
Each resource can be accessed with the full set of CRUD operations (create, read, update, delete) except
where noted.
The Release column indicates the Astra release when the resource was first introduced. This field is bolded for
the resources most recently added to the REST API.
Core resources
The core resource endpoints provide the foundational services needed to establish and maintain the Astra
runtime environment.
7
Resource Release Description
Package 22.04 The package resources provide registration of and access to package
definitions. Software packages consist of various components including files,
images, and other artifacts.
Permission 23.06 The permission resources represent permissions related to operations within
the system. The API provides read-only access to the permissions.
Role 23.06 The role resources represent roles available in the system. The API provides
read-only access to the roles.
Role binding 21.04 The role binding resources represent the relationships between specific
pairs of users and accounts. In addition to the linkage between the two, a set
of permissions is specified for each through a specific role.
Setting 21.08 The setting resources represent a collection of key-value pairs which
describe a feature for a specific Astra account.
Subscription 21.08 The subscription resources represent the active subscriptions for an Astra
account.
Task 22.11 The task resources provide read-only access to managed task and can be
used to display the status of the internal long-running tasks.
Token 21.04 The token resources represent the tokens available to programmatically
access the Astra Control REST API.
Unread notification 21.04 The unread notification resources represent notifications assigned to a
specific user but not yet read.
Upgrade 22.04 The upgrade resources provide access to software components and the
ability to initiate upgrades.
User 21.04 The user resources represent Astra users able to access the system based
on their defined role.
The managed application resource endpoints provide access to the managed Kubernetes applications.
8
Topology resources
The topology resource endpoints provide access to the unmanaged applications and storage resources.
These resources and endpoints are not currently included with the Astra Control REST API
reference documentation.
OpenAPI
The OpenAPI endpoints provide access to the current OpenAPI JSON document and other related
resources.
OpenMetrics
The OpenMetrics endpoints provide access to the account metrics through the OpenMetrics resource.
Support is available with the Astra Control Center deployment model.
9
Additional considerations
RBAC security
The Astra REST API supports role-based access control (RBAC) to grant and restrict
access to the system functions.
Astra roles
Every Astra user is assigned to a single role which determines the actions that can be performed. The roles
are arranged in a hierarchy as described in the table below.
Role Description
Owner Has all the permissions of the Admin role and can also delete Astra accounts.
Admin Has all the permissions of the Member role and can also invite users to join an account.
Member Can fully manage the Astra application and compute resources.
Viewer Restricted to only viewing resources.
This feature was introduced with the 22.04 release of the Astra REST API.
When a role binding is established for a specific user, a constraint can be applied to limit the namespaces the
user has access to. There are several ways this constraint can be defined as described in the table below. See
the parameter roleContraints in the Role Binding API for more information.
Namespaces Description
All The user can access all the namespaces through the wildcard parameter "*"". This is
the default value to maintain backwards compatibility.
None The constraint list is specified although it is empty. This indicates the user cannot
access any namespace.
Namespace list The UUID of a namespace is included which restricts the user to the single namespace.
A comma separated list can also be used to allow access to multiple namespaces.
Label A label is specified and access is allowed to all the matching namespaces.
Filtering
Collection resource filtering allows an API user to specify conditions which determine if a resource is returned
10
in the response body. The filter parameter is used to indicate the filtering condition.
Sorting
Collection resource sorting allows an API user to specify the order in which resources are returned in the
response body. The orderBy parameter is used to indicate the filtering condition.
Pagination
You can enforce pagination by restricting the number of resource instances returned on a request using the
limit parameter.
Count
If you include the Boolean parameter count set to true, the number of resources in the returned array for a
given response is provided in the metadata section.
API resources
There are several Astra features exposed through API resources that provide diagnostic information and
support.
Type Description
Event System activities that are recorded as part of Astra processing.
Notification A subset of the Events that are considered important enough to be presented to the
user.
Unread notification The notifications that have yet to be read or retrieved by the user.
Steps
1. Sign in to Astra using your account credentials as follows:
a. Astra Control Service: https://astra.netapp.io
b. Astra Control Center: Use the URL for your local environment as established during installation
2. Click the figure icon at the top right of the page and select API access.
3. Select the token or tokens you want to revoke.
11
4. Under the Actions drop-down box, click Revoke tokens.
12
Copyright information
Copyright © 2023 NetApp, Inc. All Rights Reserved. Printed in the U.S. No part of this document covered by
copyright may be reproduced in any form or by any means—graphic, electronic, or mechanical, including
photocopying, recording, taping, or storage in an electronic retrieval system—without prior written permission
of the copyright owner.
Software derived from copyrighted NetApp material is subject to the following license and disclaimer:
THIS SOFTWARE IS PROVIDED BY NETAPP “AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE, WHICH ARE HEREBY DISCLAIMED. IN NO EVENT SHALL
NETAPP BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
NetApp reserves the right to change any products described herein at any time, and without notice. NetApp
assumes no responsibility or liability arising from the use of products described herein, except as expressly
agreed to in writing by NetApp. The use or purchase of this product does not convey a license under any
patent rights, trademark rights, or any other intellectual property rights of NetApp.
The product described in this manual may be protected by one or more U.S. patents, foreign patents, or
pending applications.
LIMITED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to restrictions as set
forth in subparagraph (b)(3) of the Rights in Technical Data -Noncommercial Items at DFARS 252.227-7013
(FEB 2014) and FAR 52.227-19 (DEC 2007).
Data contained herein pertains to a commercial product and/or commercial service (as defined in FAR 2.101)
and is proprietary to NetApp, Inc. All NetApp technical data and computer software provided under this
Agreement is commercial in nature and developed solely at private expense. The U.S. Government has a non-
exclusive, non-transferrable, nonsublicensable, worldwide, limited irrevocable license to use the Data only in
connection with and in support of the U.S. Government contract under which the Data was delivered. Except
as provided herein, the Data may not be used, disclosed, reproduced, modified, performed, or displayed
without the prior written approval of NetApp, Inc. United States Government license rights for the Department
of Defense are limited to those rights identified in DFARS clause 252.227-7015(b) (FEB 2014).
Trademark information
NETAPP, the NETAPP logo, and the marks listed at http://www.netapp.com/TM are trademarks of NetApp, Inc.
Other company and product names may be trademarks of their respective owners.
13