Evergreen//One Pure1 API Guide
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 |
|---|
|
Resource |
Description |
Requirement |
|---|---|---|
|
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. |
|
|
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. |
|
|
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 |
|
|
A detailed guide to the Pure1 API. It’s sorted by alphabetical topic and provides detailed response samples. |
Public |
Evergreen//One Essentials
|
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:
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 |
|---|---|---|
|
Retrieves information about Pure1 subscriptions. Each response field begins with Array (). |
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. |
||
|
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. |
||
|
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. |
||
|
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. |
||
|
Retrieves information about Pure1 subscription licenses. Each response field begins with Array (). |
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. |
||
|
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:
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:
-
Click Try it out.
-
In the filter parameter field, enter:
expiration_date<=1736121600000{} -
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:
-
Click Try it out.
-
In the filter parameter field, enter:
quarter_on_demand.data>0{} -
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:
- Click Try it out.
- In the filter parameter field, enter:
model='FA-X70R3' - 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.