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¶
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¶
- Download and install Postman
- 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)
Hover over Metal API in the Collections pane and three dots will appear, click them to “View More Actions” and select “Edit”.
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.
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.
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
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.