In the development of FlashBlade REST 2.0, some changes occurred between REST 1.x and REST 2.0. Changes vary from endpoint strings to request parameters. See Table 1 for the corresponding endpoint changes from 1.x to 2.0. See Table 2 for global and new query changes for 2.0 endpoints. Refer to these changes if necessary to update your existing scripts to avoid process disruptions. Refer to the Pure Support site for REST API 1.x reference documentation.

Table 1. Endpoint changes between REST 1.x and REST 2.0

Table 2. Query changes for REST 2.0

The FlashBlade REST API provides simple interfaces for many Purity commands.

REpresentational State Transfer (REST) uses HTTP requests to interact with resources within the FlashBlade array. REST is an architectural style that describes the following constraints:

Clients manipulate resources through request methods, such as:

Requests can include additional parameters, either in the URL or as JSON post data. For example, the names parameter is included in the following request to list a specific file system:

GET file-systems?names=fs1

Responses return a response code and data (represented in JSON). For example, the following GET file-systems?names=fs1 request returns a response code 200 OK and the attribute details for a file systems named "fs1":

>> GET file-systems?names=fs1
 << 200 OK
  {
      "name": "fs1",
      "id": "72hty443t-876t-hryt-434d-dd54321x321f",
      "created": 1501180187000,
      "destroyed": false,
      "fast_remove_directory_enabled": false,
      "snapshot_directory_enabled": false,
      "destroyed": false,
      "time_remaining": null,
      "nfs": {
         "rules": "*(ro,root_squash)",
         "v3_enabled": true,
         "v4_1_enabled": false
      },
      "smb": {
         "enabled": false
      },
      "http": {
      "enabled": false
      },
      "provisioned": 50000,
         "space": {
         "virtual": 0,
         "unique": 0,
         "snapshots": 0,
         "data_reduction": null,
         "total_physical": 0
      }
  }

• Stateless. The necessary state to handle a request is contained in the request itself.

• Cacheable. The responses must implicitly or explicitly define themselves as cacheable.

• Client-Server. The uniform interface creates separation between client and server. Clients can be more portable, servers do not need to know anything about user interface or state.

• Layered System. A client cannot tell if it is connected directly to the server; intermediary servers can be used to improve scalability or enforce security policies.

The FlashBlade REST API provides simple interfaces for many Purity commands.

In the following example, the Purity CLI command purefs list returns the attributes for the file systems on the array:

$ purefs list fs1
Name     Size     Used     Created                     Protocols
fs1      64T      0.00     2017-06-22 19:44:17 PDT     nfs

The equivalent REST API request GET https://pure01.example.com/api/[VERSION]/file-systems produces the same results:

>> GET https://pure01.example.com/api/[VERSION]/file-systems?names=fs1
 << 200 OK

  {
     "name": "fs1",
     "id": "72hty443t-876t-hryt-434d-dd54321x321f",
     "created": 1501180187000,
     "destroyed": false,
     "fast_remove_directory_enabled": false,
     "snapshot_directory_enabled": false,
     "destroyed": false,
     "time_remaining": null,
     "nfs": {
        "rules": "*(ro,root_squash)",
        "v3_enabled": true,
        "v4_1_enabled": false
     },
     "smb": {
        "enabled": false
     },
     "http": {
        "enabled": false
     },
     "provisioned": 70368744177664,
     "space": {
        "virtual": 0,
        "unique": 0,
        "snapshots": 0,
        "data_reduction": null,
        "total_physical": 0
     }
  }

The REST API uses authentication tokens instead of credentials to create sessions. Pure Storage supports two methods for creating sessions, an API token generated by the FlashBlade or OAuth 2.0 token exchange authorization grant and JSON Web Tokens (JWTs) to authenticate to the REST API. In the following sections, we will go over the procedure for generating and using both types of tokens.

Authorization determines what the client is permitted to do within a REST session.

If Purity is integrated with a directory service, such as Microsoft Active Directory or OpenLDAP, the REST service leverages role-based access control (RBAC) to determine permission levels. In other words, the roles that are assigned to the users in a directory service are the same roles that are used in Purity and in the REST API.

Once you have created a REST API session, the requests that the client is authorized to make depend on the role of the user associated with the API token (as array administrator, storage administrator, operations administrator, or read-only user). In an OAuth session the user's role is checked against the API client's max_role and the privilege of the lesser of the two roles is applied.

The integration of RBAC in the REST API with directory services is dynamic. The API token permissions are integrated with the Active Directory permissions. Changes made to a user's Active Directory permissions affect the associated API token permissions.

For example, if a user is moved to a different directory services group and the permission level changes from read-only user to storage administrator, the associated API token permissions change as well. Permission changes made in the directory server are cached on the array and may take 30 minutes to affect the API token and OAuth.

The REST API accepts API tokens generated from the array or OAuth access tokens created by an authorized server.

API tokens are used to securely create REST API sessions. By using API tokens to authenticate, scripts do not have to expose usernames and passwords. The Purity username and password are required initially to create the API token.

API tokens are unique to the Purity user for whom it was created. Each Purity user can generate and view only their own API token. Once created, an API token is valid until it expires, deleted, or recreated.

After obtaining an API token, clients can create REST API sessions and start sending requests. Since REST API service sessions are completely separate from Purity GUI sessions, REST requests cannot be accessed through the Purity GUI.

API token management does not affect Purity usernames and passwords. For example, invalidating an API token does not invalidate the Purity username or password that was used to create the token. Likewise, changing the Purity username or password does not affect the API token.

The REST API uses authentication tokens to create sessions. All Purity users can generate their own API tokens.

Generate an API token through the CLI (pureadmin create --api-token).

Once generated, the API token is valid until it expires or is deleted or recreated. It is a best practice to set an expiration period when creating an API token for security purposes.

Creating a REST Session with an API Token

After the API token has been generated, use the token to create a REST session.

To create a REST session, the POST https://server.example.com/api/login request and API token header are required. The following example displays the creation of a REST session:

>> POST https://pure01.example.com/api/login
 Request headers: api-token: "T-e7e551be-fe5d-4669-baf5-670cd8ea0560"
<< 200 OK
username: "pureuser"
Response headers: x-auth-token: "52a8163a-803b-475b-9c53-f99f6e7f4c22"

Use the returned x-auth-token header on all REST requests during this session by including it in the headers of the request.

The session is valid until it is ended or experiences 30 minutes of inactivity.

Getting an OAuth access token begins with using the public key of a key pair to create an API client on the FlashBlade array. Afterward, an encoded JSON Web Token (JWT) that is signed with the corresponding private key can be exchanged for an access token.

Creating an API Client

Generate an SSH key pair (Public Key) if you do not already have one.

Create an API Client on the array.

pureapiclient create --max-role <role> --access-token-ttl <ttl> <API-CLIENT>

• --max-role: Array roles which dictate the amount of privilege a user has. Valid role values include: array_admin, storage_admin, ops_admin, and readonly.
• --access-token-ttl: Specify the access tokens time to live, which is the amount of time the token is valid for use. Default time to live is 1 day.
• API-CLIENT: The name for the API client you are creating.

Enter the API client public key and press Enter then press Ctrl + D.

Enable the API Client. The API client is disabled by default and must be enabled for use.

pureapiclient enable <API-CLIENT>

Generating an OAuth Access Token

Access tokens can be generated using a Python script or Postman.

Access Token using Postman

In Postman, set up the token exchange request:

POST https://server.example.com/oauth2/1.0/token

Header:

• Content-Type: application/x-www-form-urlencoded

Body:

• Select x-www-form-urlencoded
• grant -type: urn:ietf:params:oauth:grant-type:token-exchange
• subject_token: <Encoded_JWT_Token>
• subject_token_type: urn:ietf:params:oauth:token-type:jwt

Tests:

const body = pm.response.json();
tests["access_token"] = body.hasOwnProperty("access_token");
var stringed = JSON.stringify(body);
var jsonData = JSON.parse(stringed);
postman.setEnvironmentVariable("bearer_token", "Bearer " + jsonData["access_token"]);

The access token returned is used in Postman for REST 2.x API sessions. Insert the Bearer access token in the Header:

Authorization: {{bearer_token}}"

Python Script Access Token

To use a Python script to generate an access token, download this Python script and use the following syntax:

python3 fa2_token_factory.py <api_client_id> <api_key_id> <api_client_name> <api_username>
 <flashblade_host_or_ip> <path_to_private_key_file>

Example script input:

python3 fa2_token_factory.py 9012907e-28fe-4019-86ab-664e1d47fb36 48da0809-be32-4a3b-962f-f188c232ab30
 MySecondClient pureuser vm-johndoe /Users/johndoe/.ssh/fa20.pem

Example script output:

Access token for MySecondClient:

eyJraWQiOiJnbUdMYkRQU1ZMOVRBY3hNTEhNVXc4QktiUkpsIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ
 eyJhdWQiOiI5MDEyOTA3ZS0yOGZlLTQwMTktODZhYi02NjRlMWQ0N2ZiMzYiLCJzdWIiOiJwdXJldXNlciIsInJvbGUiOiJhcnJhe
 V9hZG1pbiIsImFwaWNsaWVudC1yb2xlIjoicmVhZG9ubHkiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjkwMDAiLCJpYXQiOjE1Nj
 cwMzkzMjMsImV4cCI6MTU2NzEyNTcyMywianRpIjoiMzJkM2JjMjEtZGM4My00NmZiLWE0ZTEtNzk3NjNhMjgxZWZlIn0.
NKNE-5FSrZdeFFUb0k12CFQlfe0DpZMuWnhZ8ehWJhZf37FeydX9FEbLVUZnWuoiOlg6MucuMYX6gO-8xKf8ovid8vkqmTEdhaT66
 dQvoZIyu-FEke01A2IVi18maYX3oTuwPky2c9fruaFE2a4s1YAUG5lCeG1ZyHxjiM1wRvZX_iHbe

The access token returned is used in your script/Postman/program.

Important: The py-pure-client Python SDK accepts similar parameters and automatically takes care of renewing expired tokens.

REST API requests can be performed within a REST session.

Each REST API request is comprised of a complete URL. The complete URL used to make a Purity//FB REST request includes the following components:

• Method (GET, POST, PATCH, or DELETE)
• Purity array
• REST API version
  • URI

For example, the following request lists all file systems and their attributes:

 GET https://pure01.example.com/api/[VERSION]/file-systems

Some REST API requests include additional parameters.

Parameters for GET and DELETE methods may only allow query parameters in the URL. For example, the following request, with names specified as a query parameter, lists a specific file system (named "fs1"):

GET https://pure01.example.com/api/[VERSION]/file-systems?names=fs1

All other methods, such as POST and PATCH may be specified as JSON body requests or query parameters. Refer to the [http://www.json.org/] website for more information about the JSON interchange format.

The following are examples of how different data types are formatted in JSON:

Each REST API request returns a response code. Successful requests return the response code 200 OK. Scripts must be prepared to handle responses with codes other than 200 OK.

Refer to the Response Codes table for a description of each response code.

A REST session using an API token method is valid until it is ended (invalidated) or experiences 30 minutes of inactivity. REST sessions using an OAuth access token method ends after the time to live settings on the --access-token-ttl option expires or after the 24 hour time to live default setting.

To manually invalidate an API token REST session, send the following request:

>> POST https://pure01.example/api/logout
Request headers: x-auth-token: "52a8163a-803b-475b-9c53-f99f6e7f4c22"
<< 200 OK

The FlashBlade REST API returns the following HTTP response status codes for the GET, POST, PATCH, and DELETE operations:

When submitting GET requests that return a large amount of data, include filtering, sorting, and pagination query parameters to help you better manage the results.

The sort query parameter returns the response objects of a GET request in the order specified. Sorting can be performed on any of the fields in the response, and the response objects can be sorted in ascending or descending order. To search for nested field names, use a period (.) to indicate a nested object. For example, nfs.enabled and nfs.rules.

Syntax

?sort=field_name

field_name

Name of the field to sort. field_name can be any of the fields in the response. To sort in descending order, append the minus sign (-) to the field name. To sort on multiple field names, list the field names as comma-separated values.

Examples

Example 1: Get a list of all file systems sorted in ascending order by the file system's name.

GET https://pure01.example.com/api/[VERSION]/file-systems?sort=name

Example 2: Get a list of all file systems sorted in descending order name.

GET https://pure01.example.com/api/[VERSION]/file-systems?sort=name-

Example 3: Get a list of all file systems sorted in descending order by file system size, and then sorted in ascending order by file system name.

GET https://pure01.example.com/api/[VERSION]/file-systems?sort=provisioned-,name

The filter query parameter narrows down the results of a GET request to only the response objects that satisfy the filter criteria.

Filtering with Operators

Pure Storage REST API filter queries support common comparison operators.

Syntax

?filter=field_name<operator>field_value

• field_name: Name of the field on which to create the filter. The field_name can be any of the fields in the response.

• operator: Type of filter match used to compare field_name to field_value. Filters support the following operators:

• field_value: Search value (number, date, or string) that determines the fields to be included in or excluded from the response.

Literal strings must be wrapped in quotes.

To refine the filter, include the asterisk (*) symbol as a wildcard character in the field value to represent zero or more characters. The field_value can include multiple asterisks, and the asterisks can appear anywhere in the value. For example, the request GET /file-systems?filter=name='*cat*' lists all file systems with names that contain cat, including ones that begin or end with cat, such as cat, catnap, happycats, and lolcat. If the asterisks were not included, only the file system named cat would be returned.

Examples

Example 1: Get the file systems with the snapshot directory enabled.

GET https://pure01.example.com/api/[VERSION]/file-systems?
filter=snapshot_directory_enabled='true'

Example 2: Get a list of file systems with NFS enabled.

GET https://pure01.example.com/api/[VERSION]/file-systems?
filter=nfs.v3_enabled='true'

Filtering with Functions

Purity//FB REST API filter queries support the CONTAINS and NOT functions.

Syntax

?filter=function(parameters)

Filters support the following functions:

Examples

Example 1: Get a list of all file systems with NFS enabled to true.

GET https://pure01.example.com/api/[VERSION]/file-systems?
filter=nfs.enabled='true'

Example 2: Get a list of all file systems with names that do not include fs01.

GET https://pure01.example.com/api/[VERSION]/file-systems?
filter=not(contains(name,'fs01'))

Pagination controls the amount of data returned by displaying response objects (items) as page-by-page lists.

Pagination only applies if the total number of items returned is greater than the limit specified. To determine the total number of items returned, see the total-item-count body field of the response.

The Pure Storage REST API offers two methods of pagination: page by index, and page by continuation token.

Page by Index

Page by index enables clients to control the size and starting point of a page. Use page by index, such as in GUI implementations, to navigate through response objects page by page, jump to specific pages, and jump to the first or last page. For example, to page through all results with 20 results per page, begin with start=0&limit=20.

With page by index pagination, consistency may not be guaranteed in that some data may be duplicated or missing across pages. If consistency is important, use continuation tokens.

Syntax

start=offset_index&limit=items_returned

• offset_index: Index number of the first item you want results for.

• items_returned: Maximum number of response objects returned per page.

Examples

Example 1: Get all file systems starting at the very first file system.

GET https://pure01.example.com/api/[VERSION]/file-systems?start=0

Example 2: Get 10 file systems at a time.

GET https://pure01.example.com/api/[VERSION]/file-systems?limit=10

Example 3: Get 10 file systems with index 10 to 19.

GET https://pure01.example.com/api/[VERSION]/file-systems?start=10&limit=10

Continuation Token

The REST API supports continuation tokens, giving clients the ability to paginate with some consistency guaranteed.

Page by continuation token requires the limit and continuation_token query parameters.

The limit parameter determines how many response objects (items) are returned on each page.

The token parameter is a Base64 encoded value that is used to get the next page of data. The token is taken from the response field, continuation_token. A query has reached its last page when the response does not include a token.

Syntax

limit=items_returned&continuation_token=token_string

• items_returned: Maximum number of response objects returned per page.
  • continuation_token: Token of the last/first item returned in the current paginated request. The token is used in the next submit to determine the first item that should appear on the next page. The token appears in the continuation_token response field. To ensure consistent paging, the continuation_token parameter must always be used with the sort parameter.

Examples

Example 1: Use continuation_token aWQgPSA5ODA1Mg== to get the next 10 file systems.

GET https://pure01.example.com/api/[VERSION]/file-systems?
 limit=10&continuation_token=aWQgPSA5ODA1Mg==

Example 2: Get 2 file systems with index 5 to 6, and then use the continuation token returned ( bmFtZSA9IEdJeXpPM2htZmY==) to get the next 2 file systems.

>> GET https://pure01.example.com/api/[VERSION]/file-systems?start=5&limit=2
 << {
      "total_item_count": 10,
      "continuation_token": "bmFtZSA9IEdJeXpPM2htZmY=="
      }
      "items": [
<<    {
        "name": "FS001",
        "created": 1501182540000,
        "fast_remove_directory_enabled": false,
        "snapshot_directory_enabled": true,
        "destroyed": false,
        "time_remaining":null,
        "nfs": {
           "v3_enabled": true,
           "v4_1_enabled": true,
           "rules": "*(ro,root_squash)"
        },
        "smb": {
           "enabled": false
        },
        "http": {
           "enabled": false
        }
        "provisioned": 50000,
        "space": {
           "virtual": 0,
           "data_reduction": null,
           "unique": 0,
           "snapshots":0,
           "total_physical": 0
        }
     },
...
]
>> GET https://pure01.example.com/api/[VERSION]/file-systems?
 limit=2&continuation_token=bmFtZSA9IEdJeXpPM2htZmY==
<< {
     "total_item_count": null,
     "continuation_token": "bmFtZSA9IHdpbmRvd3M=="
   }
     "items": [
   {
       "name": "FS",
       "created": 1501180869000,
       "fast_remove_directory_enabled": false,
       "snapshot_directory_enabled": true,
       "destroyed": false,
       "time_remaining":null,
       "nfs": {
          "v3_enabled": true,
          "v4_1_enabled": true,
          "rules": "*(ro,root_squash)"
       },
       "smb": {
          "enabled": false
       },
       "http": {
          "enabled": false
       },
       "provisioned": 50000,
          "space": {
          "virtual": 0,
          "unique": 0,
          "snapshots": 0,
          "data_reduction": null,
          "total_physical": 0
       }
   },
...
  ]
}

Follow these guidelines when combining sorting, filtering, and pagination:

• Sort queries can be combined. A single request can be sorted on multiple field names. For example, you can sort all file systems from largest to smallest file system size, and then sort file systems of the same size in ascending order by file system name. To sort on multiple field names, list the field names as comma-separated values.

• Filter queries can be combined using the AND and OR operators. The AND operator displays response objects that meet the criteria of all filter queries in the request. The OR operator displays response objects that meet the criteria of at least one of the filter queries in the request.

• The sort, filter, limit, and offset filters can all be combined together.

Examples

Example 1: Get a list of all file systems sorted in descending order by file system size, and then sorted in ascending order by file system name.

GET https://pure01.example.com/api/[VERSION]/file-systems?sort=provisioned-,name

Example 2: Get a list of all file systems that are greater than 10 gigabytes in size and were created after 2016-04-25T23:02:23Z.

GET https://pure01.example.com/api/[VERSION]/file-systems?
 filter=provisioned>10737418240 and created>'2016-04-25T23:02:23Z'

Example 3: Get a list of all file systems that begin with fs1, and sort the list in descending order by name.

GET https://pure01.example.com/api/[VERSION]/file-systems?
filter=name='fs1*'&sort=name-

Example 4: Get a list of either all file systems with names that include 123 and are greater than or equal to 10 gigabytes in size, or all file systems with names that include abc and are less than or equal to 10 gigabytes in size.

GET https://pure01.example.com/api/[VERSION]/file-systems?
filter=(contains(name,'123') and provisioned >= 10737418240)
or (contains(name,'abc') and size <= 10737418240)

There is a Python libary to enable easy integration with the FlashBlade Management REST API. Refer to the py-pure-client library documentation for additional information:

Pure Storage FlashBlade REST Python SDK Documentation

Pure Storage uses the OAuth 2.0 Token Exchange authorization grant and JSON Web Tokens (JWTs) to authenticate to the Pure Storage REST API. Before you can exchange the ID token for an access token, create and enable the API client to generate the key_id, id, and issuer values. These values will be used as JWT claims for the subject_token parameter.

Active Directory configuration joins a server to the domain and manages its computer account. Authentication for NFS or SMB is performed using Kerberos. This configuration is also used to authorize users by mapping identities across the NFS and SMB protocols by using LDAP queries.

Manage administrators, including their REST API Token and public key for SSH access. The array has a single default administrative account named pureuser. Additional administrators and their administrative roles can be added by configuring the management directory service for the array or by creating local administrative users. The available administrative roles are array_admin, storage_admin,readonly, ops_admin.

Alerts indicate significant events that occur on the array, including whenever a component degrades or the capacity threshold of the component is reached.

Alert watchers receive email notifications when alerts occur on an array.

An API client represents an identity type. API clients are created on the array. To create an API client, register and then enable it on the array. After the API client has been created, the user name (sub) and identity tokens (kid and aud tokens) that are issued by the API client are used as claims for the JSON Web Token that you create to authenticate into the REST API.