Skip to main content
Pure Technical Services

Evergreen//One Pure1 API Guide

Currently viewing public documentation. Please login to access the full scope of documentation.

KP_Ext_Announcement.png

Introduction

The Evergreen//One Pure1 REST API enables seamless access to valuable data from the Subscriptions page of the Pure1 Manage service (Pure1). With this comprehensive API guide, you'll gain the confidence to harness the full potential of Evergreen//One, empowering you to interact effortlessly with the REST API. Whether you're an experienced developer or new to APIs, this guide caters to all skill levels, offering a user-friendly approach to Evergreen//One and its API functionalities.

Resources

Evergreen//One is a storage as-a-service (STaaS) platform that unifies on-premises and public cloud storage resources in a single data storage subscription. This document solely covers Evergreen//One—for more general Pure1 REST API documentation and information about setup and configuration, refer to the table below.

Base URL

https://api.pure1.purestorage.com/

 

Resource

Description

Requirement

REST API - Quick Setup Guide

A quick setup guide for the Pure1 API, including steps necessary for this document.

Access to the Pure Storage support site and access to Pure1. Use Pure1 credentials to log in and view.

Pure1 Manage - REST API Reference Guide

A full reference guide for the Pure1 API.

Access to the Pure Storage support site and access to Pure1. Use Pure1 credentials to login and view.

Swagger: Pure1 Public API

A Swagger guide for the Pure1 public API. This guide provides detailed information about each type of query you may make to Pure1. You can quickly access these requests by expanding the section and clicking the “Try It Out” button.

Public

ReDoc: Pure1 Public REST API

A detailed guide to the Pure1 API. It’s sorted by alphabetical topic and provides detailed response samples.

Public

Evergreen//One Essentials

undefined

Evergreen//One General Terminology

Subscription

A collection of licenses that share the same billing characteristics, billing address, expiration date, renewal cycle, terms, etc.

 

A subscription can contain licenses of different tiers, licenses with different locations, or both.

License

Describes storage characteristics with three dimensions: 

  • Service tier/SLA* (eg: Block Ultra, Block Capacity)

  • Location

  • Reserve capacity (eg: 50 TiB)

While it is not possible to update the service tier and location, new licenses can be created, and the reserve capacity can be modified.

 

Each license may contain a marketplace partner and a marketplace partner reference ID.

 

A license also contains a list of resources. 

Resources

The type of appliances contained in a license—FlashArray, FlashBlade, or CBS.

Subscription Object Models

ID

UUID

Name

Immutable, chosen by Pure

Expiration Date

Timestamp in milliseconds since Unix Epoch

Service

Eg: Evergreen//One (Block Storage Service)

Status

Active, terminated, poc-expired, or signed

License Object Models

ID

UUID

Name

Immutable, chosen by Pure

Subscription

Reference to the subscription this license belongs to

Service Tier

The service tier selected for a specified license (eg: Block Ultra, Block Capacity)

Resources

List of appliances in a specified license

Reservation

The current reserved capacity

Usage

The current usage

Average On-Demand

Estimated daily on-demand usage of the license from the start of the current calendar quarter to the most recent date

*Service Level Agreement

API Access

To access the Pure1 API, an application must be registered in the Pure1 GUI. The steps to do so are explained in detail in the Pure1 Manage - REST API Reference Guide. There is no extra configuration needed for partners—they have access to their own subscriptions as well as the one they are the billing partners for.

Refer to the Authentication for additional steps to access the Pure1 API.

Important Endpoints For Managing Evergreen//One Subscriptions

Endpoint

Description

Response Fields

subscriptions

Retrieves information about Pure1 subscriptions.

 

Each response field begins with Array ().

_as_of

Type: integer <int64>

The freshness of the data (timestamp in millis since epoch).

id

Type: string

A non-modifiable, globally unique ID chosen by the system.

name

Type: string

A non-modifiable, locally unique name chosen by the system.

expiration_date

Type: integer <int64>

Date when the subscription expires. Represented as a timestamp of 00:00 on that date in UTC, in milliseconds since the UNIX epoch.

service

Type: string

The service type of the subscription. Values include Evergreen//One, Evergreen//Flex, FlashStack as a Service, Storage as a Service, Evergreen//One (Block Storage Service), Evergreen//One (File and Object Storage Service), Evergreen//One (Data Protection Service), and Pure1 Subscription.

start_date

Type: integer <int64>

Date when the subscription starts. Represented as a timestamp of 00:00 on that date in UTC, in milliseconds since the UNIX epoch.

status

Type: string

Current status of the subscription. Values include active, terminated, poc-expired, and signed.

subscription-licenses

Retrieves information about Pure1 subscription licenses.

 

Each response field begins with Array ().

_as_of

Type: integer <int64>

The freshness of the data (timestamp in millis since epoch).

id

Type: string

A non-modifiable, globally unique ID chosen by the system.

name

Type: string

A non-modifiable, locally unique name chosen by the system.

average_on_demand

Type: object

Estimated daily on-demand usage of the license from the current calendar quarter to date.

expiration_date

Type: integer <int64>

Date when the license expires. Represented as a timestamp of 00:00 on that date in UTC, in milliseconds since the UNIX epoch.

marketplace_partner

Type: object

Reference information about the marketplace partner of this license.

reservation

Type: object

Current reservation amount of the license.

resources

Type: array of objects

References to the resources that operate under this license.

service_tier

Type: string

The tier of the service for the license.

start_date

Type: integer <int64>

Date when the license starts. Represented as a timestamp of 00:00 on that date in UTC, in milliseconds since the UNIX epoch.

subscription

Type: object

A reference to which subscription this license belongs.

usage

Type: object

Usage of the license, averaged over the last day.

 

subscription-assets

Retrieves information about Pure1 subscription assets.

authorization

Type: string

Access token (in JWT format) required to use any API endpoint (except /oauth2)

x-request-id

Type: string

Supplied by client during request or generated by server.

continuation_token

Type: string

An opaque token used to iterate over a collection. The token to use on the next request is returned in the continuation_token field of the result. Single quotes are required around all strings.

filter

Type: string

Exclude resources that don't match the specified criteria. Single quotes are required around all strings inside the filters.

ids

Type: string

A comma-separated list of resource IDs. If there is not at least one resource that matches each id element, an error is returned. Single quotes are required around all strings.

limit

Type: integer ($int32)

The offset of the first resource to return from a collection.

names

Type: array[string]

A comma-separated list of resource names. If there is not at least one resource that matches each name element, an error is returned. Single quotes are required around all strings.

offset

Type: integer ($int32)  

The offset of the first resource to return from a collection.

sort

Type: integer ($int32)  

Sort the response by the specified fields (in descending order if '-' is appended to the field name). If you provide a sort you will not get a continuation token in the response.

subscription_ids

Type: array[string]

A comma-separated list of subscription IDs. If there is not at least one resource that matches each subscription.id element, an error is returned. Single quotes are required around all strings.

subscription_names

Type: array[string] 

A comma-separated list of subscription names. If there is not at least one resource that matches each subscription.name element, an error is returned. Single quotes are required around all strings.

license_ids

Type: array[string]   

A comma-separated list of subscription license IDs. If there is not at least one resource that matches each license.id element, an error is returned. Single quotes are required around all strings.

license_names

Type: array[string]  

A comma-separated list of subscription license names. If there is not at least one resource that matches each license.name element, an error is returned. Single quotes are required around all strings.

For examples of various ways to interact with information from these endpoints, refer to the Example Queries section.

Important Metrics for Evergreen//One Subscriptions

Metrics play a crucial role in helping developers understand and optimize the performance of their applications. In short, Metrics provide valuable data and insights about how an API is performing, how it's being used, and its impact on the systems it interacts with.

The below metrics are the most important to know for Evergreen//One.

Metric

Description

subscription_license_effective_used_space

Effective used capacity of the entire license

subscription_license_on_demand_space

On-demand capacity of the entire license

subscription_license_reserved_space

Capacity reservation for the license

subscription_license_on_demand_charge

Estimated on-demand bill for the entire license

array_effective_used_space

Effective used capacity of a specified array

array_data_reduction

The data reduction ratio (DRR) of a specified array

array_on_demand_space

The remaining amount of on-demand space for a specified array

For more information, refer to the Subscription License Metrics section of the Pure1 Manage REST API Reference Guide.

Authentication

pure1_token_factory.py: https://support.purestorage.com/@api....py?revision=2

Additional Notes about Authentication

Example Queries

API queries follow a specific structure and syntax to effectively communicate with the REST API. To make a request, you need to specify the HTTP method, the endpoint URL, and, in some cases, include additional parameters or a request payload. The most common HTTP methods in API queries are GET, POST, PUT, and DELETE. For instance, to retrieve information about a specific resource, you would use the GET method along with the appropriate endpoint URL. Parameters can be added to refine the query, such as filtering results based on specific criteria or paginating through large datasets. Additionally, for certain operations that require creating or updating data, you may need to include a request payload, which is typically formatted in JSON or XML.

Below are examples of queries to retrieve information about your Evergreen//One subscription. The first section below, Detailed Example Queries, includes a detailed breakdown of the GET License Usage request URL and what each piece of it means. The examples after that aren’t broken down the same way, but the same principles apply.

Detailed Example Queries

This section covers two essential API queries: Get License Usage and Get Array Usage. Understanding usage information is crucial for optimizing resource utilization and gaining valuable insights into your interactions with our platform.

In the first subsection, Get License Usage, we will explore how to retrieve comprehensive usage data for specific licenses. We will break down the request structure, enabling you to efficiently track and analyze license utilization.

Moving on to the second subsection, Get Array Usage, we will focus on acquiring usage information for arrays within our system. We will guide you through constructing the query to obtain array-specific metrics, empowering you to make informed decisions regarding your array resources.

Note: Metrics are best queried from the metrics and metrics history endpoints.

Get License Usage

One of the most common GET requests is for license usage. As previously mentioned, licenses are groupings of arrays, so this request is to collect information about the averaged usage across all arrays in a specific license over a calendar quarter

Note: The license endpoint metrics are mostly informational. On-demand usage is averaged over a calendar quarter, which may not be useful for customers billed monthly, and the usage represents the last data point collected, but billing is done by averaging all data points in one UTC day.

To retrieve the on-demand space usage data for a specific license (ID 123-456-7890) between February 22nd and February 24th 2021, with data points recorded once per day, refer to the following:

https://api.pure1.purestorage.com/metrics/history?names='subscription_license_on_demand_space'&resource_ids='123-456-7890'&start_time=1613952000000&end_time=1614124800000&aggregation='avg'&resolution=86400000

Here is a breakdown of each parameter in the URL:

GET/metrics/history?
names='subscription_license_on_demand_space'
&resource_ids='123-456-7890'
&start_time=1613952000000
&end_time=1614124800000
&aggregation='avg'
&resolution=86400000

The below table displays a more in-depth view of what each parameter means along with an example value and formatting information.

Parameter

Example Value

Description

names

'subscription_license_on_demand_space'

The name(s) of the metric(s) you are querying; simple quotes around strings

&resource_ids

'123-456-7890'

The UID(s) of the resource(s) you are querying; simple quotes around strings

&start_time

1613952000000

Milliseconds since unix epoch UTC

&end_time

1614124800000

Milliseconds since unix epoch UTC

&aggregation

'avg'

Simple quotes around strings

&resolution

86400000

24 hours in milliseconds

Get Array Usage

To query usage at the array level instead of the license level, it is a similar request.  You can query array usage information by using the array_effective_used_space, array_data_reduction, and array_on_demand_space metrics. For example, see the GET array usage request below:

GET /metrics/history?
names='array_effective_used_space'
&resource_ids='<arrayID>'
&start_time=1613952000000
&end_time=1614124800000
&aggregation='avg'
&resolution=86400000

To request array data reduction or array on demand space, you just need to swap out the names field with either array_data_reduction or array_on_demand_space.

Get all subscriptions that need to renew soon

Request URL: GET https://api.pure1.purestorage.com/api/1.2.b/subscriptions?filter=expiration_date<=1736121600000

In Swagger, open the GET /api/1.2.b/subscriptions section:

  1. Click Try it out.

  2. In the filter parameter field, enter: expiration_date<=1736121600000{}

  3. Click Execute

Get all licenses that have on demand usage this quarter

Request URL: GET https://api.pure1.purestorage.com/api/1.2.b/subscription-licenses?filter=quarter_on_demand.data>0

In Swagger, open the GET /api/1.2.b/subscription-licenses section:

  1. Click Try it out.

  2. In the filter parameter field, enter:  quarter_on_demand.data>0{}

  3. Click Execute.

Get all assets that belong to a subscription and have a specific controller model

Request URL: GET https://api.pure1.purestorage.com/api/1.2.b/subscription-assets?subscription_names='00056741'&filter=model='FA-X70R3'

In Swagger, open the GET /api/1.2.b/subscription-assets section:

  1. Click Try it out.
  2. In the filter parameter field, enter:  model='FA-X70R3'
  3. Click Execute.

Conclusion

In conclusion, this guide has provided a comprehensive overview of Evergreen//One and how to effectively interact with the corresponding REST API. We covered the necessary resources, basic concepts, authentication process, constructing queries, and retrieving usage information. By following the guidelines and examples provided, you can confidently utilize the API to achieve your goals. For further assistance, contact your designated CSM or review the documentation linked in the Resources section.