VXRAIL 7.0.

XXX
FEATURE - REST API

DOWNLOADABLE CONTENT

DOWNLOADABLE CONTENT
 ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page i

Table of Contents

VxRail 7.0.XXX Feature - REST API .................................................................................... 4

VxRail API Introduction ............................................................................ 5

VxRail API Introduction ........................................................................................................ 6

API Overview ....................................................................................................................... 6
VxRail API Benefits .............................................................................................................. 6
Knowledge Check - Identify the VxRail API Benefits ............................................................ 7

VxRail API Functionality ........................................................................... 8

VxRail API Functionality ....................................................................................................... 9

VxRail API Request Structure .............................................................................................. 9
VxRail API Responses ....................................................................................................... 11

Knowledge Check: VxRail API Functionality ......................................................... 13

Knowledge Check - VxRail API Request Structure............................................................. 13
Knowledge Check - VxRail API Responses ....................................................................... 13

VxRail Onboard API Documentation ..................................................... 14

VxRail Onboard API Documentation .................................................................................. 15

Locate the VxRail Onboard API Documentation ................................................................. 15
Examples of Available APIs ............................................................................................... 18
Interaction: Use VxRail API Onboard Documentation to Request Chassis Information ...... 20
Interaction: Request VxRail System Information Using the VxRail API............................... 20

Knowledge Check: VxRail Onboard API Documentation ..................................... 21

Knowledge Check - Available APIs .................................................................................... 21
Knowledge Check: VxRail Onboard API Documentation .................................................... 21

VxRail API Resources............................................................................. 22

VxRail API Resources ........................................................................................................ 23

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page ii © Copyright 2022 Dell Inc.

 VxRail API Resources ........................................................................................................ 23

Knowledge Check: VxRail API Resources ............................................................. 28

Knowledge Check: VxRail API Resources ......................................................................... 28
You Have Completed This Content .................................................................................... 29

Appendix ................................................................................................. 31

Glossary .................................................................................................. 33

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2020 Dell Inc. Page iii

Knowledge Check: VxRail API Functionality

VxRail 7.0.XXX Feature - REST API

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 4 © Copyright 2022 Dell Inc

.
VxRail API Introduction

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2020 Dell Inc. Page 5

Knowledge Check: VxRail API Functionality

VxRail API Introduction

API Overview

What Is an API?

Application Programming Interfaces (APIs) establish rules that enable interactive

applications to communicate. REpresentational State Transfer (REST) API is a
specific design methodology for API communications. REST API is an architectural
style for client/server communications.

A useful analogy for APIs is human language. Language enables humans to

communicate with each other by providing rules and structure. APIs function in a
similar manner.

What Is the VxRail API?

Client/Server communication high-level diagram.

VxRail includes an implementation of REST API called VxRail API, which is part of
VxRail Manager. The VxRail API provides management functions for installation,
upgrade, and expansion to API clients. The client uses HTTP to send VxRail API
requests, and the server uses HTTP to respond.

VxRail API Benefits

There are numerous benefits of using the VxRail API. To explore two benefits in
more detail, select each tab.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 6 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail API Functionality

Automating Operations

The VxRail API supports automation tools for performing upgrade operations of
one or more VxRail systems. Automation reduces the amount of human time and
intervention during an upgrade. Automation tools work with the VxRail API to
perform:

• Life Cycle Management (LCM).

• Upgrade pre-checks.
• Upgrades.
• Upgrade post-checks.
• Cluster shutdowns.
• Log collection.

Gathering information

The VxRail API can be used to programmatically collect:

• System Health, Heartbeat, and Available Node information.

• Status of Network Environment Settings.
• Status of all running operations on a cluster or the status of a specific operation.
• Individual logs or log bundles.

Knowledge Check - Identify the VxRail API Benefits

1. Which of the following is supported by the VxRail API? Select three (3).
a. Automation of upgrade operations.
b. Programmatic gathering of VxRail statistics including: System Health,
Heartbeat, and other information.
c. Programmatic collection of VxRail logs.
d. Continuous polling for performance statistics.
e. Automatic security audits of VxRail systems.
f. Remote upgrade of iDRAC related software only.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 7

VxRail API Functionality

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 8 © Copyright 2022 Dell Inc.

 Knowledge Check: VxRail API Functionality

VxRail API Functionality

VxRail API Request Structure

The VxRail API request structure is based on the HTTP protocol. To learn about
the four basic parts of a VxRail API request, select each tab.

VxRail API Base URL

The VxRail API Base URL has a similar purpose to

URLs used on the worldwide web. It points the API VxM API Base URL
client to whatever resource is required from the VxRail (https://<VxM_IP>/rest/vxm/)

API.

VxM API Methods

The "HTTPS" is there This portion of the URL will

because VxRail uses VxM API Headers
remain regardless of the
Transport Layer Security IP address of the VxRail API call
(TLS). Manager (VxM) instance

VxM API Body

VxM API Request Structure

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 9

Knowledge Check: VxRail API Functionality

VxRail API Methods

The HTTP Method tells the VxRail Manager what to

do with the VxM resource. VxM API Base URL

VxM API Methods

(GET, POST, PUT, PATCH, DELETE)

VxM API Headers

VxM API Body

VxM API Request Structure

GET Asks the VxRail Manager to retrieve a

resource

POST Asks the VxRail Manager to create a

resource

PUT Asks the VxRail Manager to replace an

existing resource

PATCH Asks the VxRail Manager to apply partial

modification to a resource

DELETE Asks the VxRail Manager to remove a

resource

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 10 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail API Functionality

VxRail API Headers

VxRail API Headers provide additional data to the

VxRail Manager about the VxRail API request invoked VxM API Base URL
by the client.

The most common VxRail API Header is

Authentication, because it is required with all VxRail VxM API Methods
API requests.

The VxRail API uses the VMware vCenter or Platform VxM API Headers
Services Controller (PSC) single sign-on (SSO) for (Authentication)

authentication. Authorized users need to leverage

appropriately privileged accounts from a vSphere
identity source VxM API Body

For more details on the VxRail API Header, see the

Dell Technologies Developer Portal for VxRail API. VxM API Request Structure

VxRail API Body

The VxRail API Body uses the JSON format.

VxM API Base URL
Methods like Post, Put, Patch, and Delete typically
send additional information in the Body of the request.
For example, the lcm/upgrade VxRail API request
requires several parameters in the body which provide VxM API Methods
information to the VxRail Manager. These parameters
include the LCM composite upgrade bundle, and
credentials for vCenter. VxM API Headers

For specific details on the VxRail API Body parameter,

see the VxRail API User Guide. VxM API Body
(Data)

VxRail API Responses VxM API Request Structure

After VxRail Manager receives an API request, the

server responds to the client. VxRail API responses have a structure similar to
VxRail API requests, since they are also based on the HTTP protocol. The VxRail

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 11

Knowledge Check: VxRail API Functionality

API response contains a three-digit status code and a body. The body of the
response is provided in JSON format.

Once the client receives the API response, the VxRail API interaction between the
VxRail Manager and the client is complete.

Status Codes

The API client would use the status code to determine the next step; retry, wait,
error out, or warn. For example, some requests may return a 202 code (API
request accepted for processing, but not completed) and include a Request ID in
the response body. The API client could then send another request with the
request ID to check on the status of the previous request until the operation is
successful.

The table lists some of the VxRail API status codes. Sometimes the description
may be more detailed based on the API call that was made.

API Description Response Category

Code

200 Successful operation Success

202 API request accepted for processing, Success

but not completed

207 Retrieved a partial list of slot mappings Success

for hosts

400 Invalid request parameters Client Issue

401 Requires user authentication Client Issue

403 Inefficient privileges to perform the task Client Issue

404 Requested resource not found Client Issue

409 Conflict request Client Issue

500 General error occurred Server Issue

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 12 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail API Functionality

Knowledge Check: VxRail API Functionality

Knowledge Check - VxRail API Request Structure

1. Which components are required for a VxRail API request? Select three (3).
a. Base URL
b. Method
c. Header
d. Body
e. Parameter
f. VxRail Node ID

Knowledge Check - VxRail API Responses

2. When an API call to VxRail Manager has been submitted, what part of the
response indicates that the request was not completed?
a. Status code
b. Body
c. Header
d. Schema

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 13

VxRail Onboard API Documentation

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 14 © Copyright 2022 Dell Inc.

 Knowledge Check: VxRail API Functionality

VxRail Onboard API Documentation

Locate the VxRail Onboard API Documentation

VxRail Manager provides interactive API documentation at

https://<VxRail_Manager_IP_or_FQDN>/rest/vxm/api-doc.html.

The VxRail API documentation describes:

• Available endpoints and operations on each endpoint.
• Request and Response schemas for each endpoint.
• Authentication.

The VxRail onboard API documentation is potentially upgraded when VxRail

Manager is upgraded depending upon changed API functionally. Additionally it
enables users to execute out the API calls directly in the browser. To learn about
the VxRail Rest API UI, select each hotspot.

VxRail Onboard API Documentation

1: To retrieve a list of VxRail chassis' and information about the nodes in each
chassis, the Get a list of VxRail chassis(v1)API call would be used.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 15

Knowledge Check: VxRail API Functionality

Some calls have multiple versions. As an example, the Get a list of VxRail
chassis(v4)API provides the same information as the v1 API but also adds
support for satellite nodes.

The HTTP method that is used in the example is GET, and is displayed in green.

2: The VxRail API uses the VMware vCenter for Single Sign-On (SSO)
authentication. Use a vCenter SSO account with the proper access when using the
VxRail API.

VxRail Manager and VxRail API do not provide management of vCenter user
accounts. Manage your credentials using vSphere.

The API passes credentials to the vCenter for authentication. HTTP Basic
authentication authorization method is configured for the VxRail REST API.

API requests can be sent from the onboard API documentation using the Send
Request button.

3:

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 16 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail API Functionality

The request sample provides an example of the request to

be sent. This sample can be created in multiple
programming languages.

4: The response example section provides an example of

the response body. A response is usually JSON which
contains name/value pairs. The "value" returned matches
the data type specified in the response example as defined
by the schema for a given API. The client will properly
process the value and associated data type returned by the
VxRail API.

The VxRail API primarily uses string, integer, and boolean

data types organized individually, as arrays, or as objects.

Available programming
language

API Response Example

5: After VxRail Manager receives an API request from the API client, it sends a
response back to the client. VxRail API responses have a schema similar to VxRail
API requests.

The VxRail API response contains a status code. The API client would use the
status code value in a conditional to determine what to do next. For example retry,
wait, error out, warn.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 17

Knowledge Check: VxRail API Functionality

6: The UI displays the API endpoint path, and a brief description. The endpoint
path would be appended to the base URL. For example: https://<VxM IP or
FQDN>/rest/vxm/v1/chassis.

Examples of Available APIs

There are two types of API Requests; Asynchronous and Synchronous.

Examples of asynchronous operations include initializing a cluster, cluster

shutdown, add/remove a node, software upgrade, prechecks, and validations.
These operations take significant time to complete. All remaining endpoint
operations are examples of synchronous operations.

The VxRail onboard API documentation can be used for both Day 1 and Day 2
operations. To learn about the differences between Day 1 and Day 2 operations,
select the tabs.

Day 1 Operations

Day 1 operations all pertain to the readiness of nodes that are used to form a
cluster and the cluster formation itself. Day 1 VxRail operations include: scanning
for available hosts, getting disk slot mappings of hosts, re-IP the VxRail Manager to
a permanent address, cluster initialization dry run, cluster initialization, and
monitoring the cluster initialization status.

The Get disk slot mappings for hosts is an example of a Day 1 operation.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 18 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail API Functionality

Get disk slot mappings for hosts

Day 2 Operations

Day 2 operations can be run after deployment of a VxRail cluster. Day 2 operations
all pertain to the maintenance of nodes after the cluster formation itself. The
Remove a host from the cluster is a Day 2 operation.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 19

Knowledge Check: VxRail API Functionality

Remove a host from the cluster

Interaction: Use VxRail API Onboard Documentation to

Request Chassis Information

The web version of this content contains an interactive activity.

Interaction: Request VxRail System Information Using the

VxRail API

The web version of this content contains an interactive activity.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 20 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail Onboard API Documentation

Knowledge Check: VxRail Onboard API Documentation

Knowledge Check - Available APIs

1. A VxRail implementer has sent an API request to VxRail Manager before the
deployment of a new cluster. The VxRail Manager responded with a request ID
and 202 status code. What type of request was sent? Select two (2).
a. Day 1
b. Day 2
c. Asynchronous
d. Synchronous

Knowledge Check: VxRail Onboard API Documentation

Use the VxRail onboard API documentation simulator below to answer the
questions. Scroll down to view both questions.

The web version of this content contains an interactive activity.

2. Which VxRail API endpoint is used to add a VxRail node to an existing VxRail
cluster?
a. /v1/cluster/expansion/validate
b. /v1/cluster/expansion
c. /v2/hosts
d. /v1/host-folder/expansion

3. Which HTTP method is used when sending a VxRail cluster expansion API
request?
a. POST
b. PUT
c. GET
d. PATCH

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 21

VxRail API Resources

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 22 © Copyright 2022 Dell Inc.

 Knowledge Check: VxRail Onboard API Documentation

VxRail API Resources

VxRail API Resources

To learn about the available VxRail API resources, select each tab:

VxRail API Documentation on the Dell Technologies Developer Portal

The Dell Technologies Developer Portal provides a catalog of platform APIs to fit
your development and automation needs. The VxRail API is in the catalog. The
Developer Portal contains a VxRail API Introduction, a Getting started guide, a
What's new page, and a list of resources. In addition, the Dell Technologies
Developer Portal allows you to view details about each of the APIs. For more
information, go to the Dell Technologies Developer Portal for VxRail API.

Select version specific documentation.

Dell Technologies Developer Portal - Explore APIs - VxRail API.

VxRail Onboard API Documentation

The VxRail onboard API documentation provides available endpoints and

operations for each endpoint, input parameters for each operation, and

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 23

Knowledge Check: VxRail Onboard API Documentation

authentication methods. The VxRail onboard API documentation is a programmatic

interface which can be used for performing VxRail Day 1 and Day 2 tasks. The
onboard documentation is updated as the APIs evolve and is available at
https://<VxRail_Manager_IP|FQDN>/rest/vxm/api-doc.html.

VxRail onboard API documentation - Overview page.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 24 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail Onboard API Documentation

VxRail API PowerShell Modules

Windows PowerShell example using Get-Help to retrieve help for the VxRail API PowerShell
Modules Get-SystemInfo cmdlet.

The VxRail API Powershell modules enable an administrator to run PowerShell

cmdlets to manage their VxRail system. The administrator can perform tasks such
as an LCM upgrade, or get system information about a specific server. Cmdlets
from the VxRail API PowerShell Modules can be used in individual commands or
scripts for task automation.

Search for "PowerShell" on the VxRail product support page to download the
VxRail API PowerShell Modules.

View a brief demo on using the VxRail API PowerShell cmdlets.

VxRail RESTful API Cookbook

The VxRail RESTful API Cookbookcontains sample VxRail RESTful API workflows.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 25

Knowledge Check: VxRail Onboard API Documentation

VxRail RESTful API Cookbook example page.

Ansible Modules for VxRail

Dell provides sample Ansible Playbooks that can be used for automation of Day 1
and Day 2 VxRail tasks. The Ansible modules can be used independently for ad
hoc commands. For more information, go to the Ansible Modules for Dell EMC
VxRail.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 26 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail Onboard API Documentation

Ansible Modules for Dell EMC VxRail landing page.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 27

 Knowledge Check: VxRail API Resources

Knowledge Check: VxRail API Resources

Knowledge Check: VxRail API Resources

Use the Dell Technologies Developer Portal for VxRail API to answer the following
question.

1. A developer is getting started with the VxRail API. What is the VxRail API base
URL?
a. https://<VxM_IP>/rest/vxm/
b. https://<VxM_IP>/vxm/
c. http://<VxM_IP>/rest/vxm/
d. https://<VxM_IP>/rest/vxm/v1

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

Page 28 © Copyright 2022 Dell Inc

.
 Knowledge Check: VxRail API Resources

You Have Completed This Content

Click the Save Progress and Exit button in the course menu to record this
content as complete.
Go to the next learning or assessment, if applicable.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 29

Appendix

PowerShell cmdlets
Commands are available for the following modules:

• VxRail.API.Certificate
• VxRail.API.Chassis
• VxRail.API.Cluster
• VxRail.API.Common
• VxRail.API.Disk
• VxRail.API.Host
• VxRail.API.LCM
• VxRail.API.Support
• VxRail.API.SysBringup
• VxRail.API.System
• VxRail.API.Telemetry
• VxRail.API.VC

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2020 Dell Inc. Page 31

Glossary
Asynchronous
Asynchronous API request operations are long running (long duration) tasks that
return a Request ID (UUID) in the Response Body. These requests have a Status
Code of 202 in the response. The request Id is used to repeatedly query the
progress until completion.

Synchronous
Synchronous API request operations are short duration requests. The request is
made, an operation immediately completes, and a status code is returned in the
body. These requests have a Status Code of 200 in the response.

ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2020 Dell Inc. Page 33

 ES102CPX02009 ~ VxRail 7.0.XXX Feature - REST API-SSP

© Copyright 2022 Dell Inc. Page 34