Using Postman to Explore the Equinix Metal API

What's in this guide?

You're certainly welcome to make handcrafted, artisanal requests to the Equinix Metal API, though that'll take quite a bit of time (and is error-prone). Using an API tool like Postman will allow you to see what's possible, and to quickly make error-free requests. In this guide we'll cover downloading, installing, and configuring Postman to use the Equinix Metal API, then making requests and visualizing the responses.

You will need

• Postman app or account
• Equinix Metal API Key
• Equinix Metal API Swagger Definition

Understanding the Equinix Metal API and Postman

The Equinix Metal API allows the creation, deletion and management of hardware and networking configuration connected to your Equinix Metal account.

Postman is a collaboration platform for API development, as such it's a great tool for getting to know an unfamiliar API.

Installing and configuring Postman

1. Download and install Postman

2. Open Postman and click File > Import > Link, then enter https://api.equinix.com/metal/v1/api-docs (the Equinix Metal Swagger definition) into the "Enter a URL" box. Click "Continue". Click "Import". This will generate a collection called Metal API with 184 requests populated. (This may take ~30 seconds)

3. Hover over Metal API in the Collections pane and three dots will appear, click them to “View More Actions” and select “Edit”.

   

4. In the “Authorization” tab, enter your Equinix Metal API Key / Token (from console.equinix.com) in the “Value” field for the key X-Auth-Token header.

   

5. In the the “Variables” tab and ensure the remove the "Current Value" for variable "BaseUrl" from the baseUrl is api.equinix.com/metal/v1 (No leading //). Click "Update"

   

Making Requests

Clicking the down arrow on "Metal API" in the Collections pane (left side) will expand the imported requests, arranged by endpoint. Clicking the name of a request "Retrieve all facilities" for example will open that request in the editor. Cliicking the blue "Send" button will make that request to the API, the response body will appear below. Postman pretty prints the returned JSON, making it easier to read.

Visualizations

To visualize the response, code added to the Tests script for the request will be applied to the data and viewable it in the Visualize tab when the request runs. Below, creating an HTML / CSS table and using JSONPath for live filtering the JSON response are illustrated.

HTML / CSS Table view of available facilities

HTML / CSS Table styled to show capacity for plans per facility

Postman collection with example HTML / CSS table visualization code

JSONPath filtering of Operating System response showing OS name only Postman collection with example JSONPath filter

Watch out for...

To use the Equinix Metal API, you'll need an Equinix Metal account in good standing.

The Equinix Metal API can perform most any action on your account, including creating new machines (incuring charges), and deleting running machines. Use care when making requests.

So, what’s next?

Equinix Metal API
Postman Learning Center
Visualizing Postman Responses
Filter Response Body data using JSONPath