Using REST APIs for Automation, Part 1.

REST APIs are an increasingly common way of communicating with data center systems of all kinds. We use them to set policy, to write custom automation, and to test applications. To those of us who started our careers as sysadmins, they can be quite intimidating, but if we break them down, we find that they actually serve as a clean, simple way of providing programmatic access to a system’s basic functions.

What is REST?

REST stands for Representational State Transfer, and is a standard for programmatic communication between systems without relying on a domain-specific language. REST calls can be made via any number of languages, including Python, Ruby, JavaScript, PowerShell, and regular shell scripting via curl.

Let’s start with a real-world example: a REST call to our InfoBlox appliance requesting a list of all the networks it manages:


curl -k -u username:password -X GET

https://InfobloxFqdnOrIPHere/wapi/v1.7/network -d network=10.1.1.0/24

A REST call has several parts:

  • The host
    • The target host listening for API calls—in our case, this is our InfoBlox GridMaster, but it could be your ServiceNow instance, your custom application, or any other RESTful API
  • Authentication,
    • In this case we’re using HTTPS Basic Authentication, which sends a username and password via HTTP over SSL/TLS.
    • There are a variety of methods, including Basic, token (OAuth), and certificate—the method you use will depends on the product.
  • The method (usually one of GET, POST, PUT, PATCH, DELETE)
    • These methods are used for retrieving data, as well as CRUD operations. Respectively, they retrieve, create, replace, update and delete data from a resource.
  • The resource
    • REST APIs have various resource “endpoints”—these represent the various resources within the system you might want to configure or query.
    • In our InfoBlox example, endpoints include networks, IP addresses (of both IPv4 and IPv6), DHCP leases, and many others.
    • The format for an endpoint will be a URL, usually the host followed by an API version, then an endpoint, and then any parameters, as in the below examples:
      • https://infoblox.corp.com/wapi/v1.7/network
      • https://infoblox.corp.com/wapi/v1.7/ipv4adddress
  • The parameters
    • In our example, this is “-d 10.1.1.0/24”
    • This could be many things, depending on your particular API
    • The URL could also be formatted: …/wapi/v1.7/network?network=10.1.1.0/24
  • The headers
    • Headers tell the REST host the kind of data we’re sending, the kind we’re expecting in the response, and many other things depending on the particular API.
    • In this example, we’ve specified that we want a JSON response
  • The payload
    • This is usually a JSON, and contains the data with which to create or update the resource
    • GET requests will have no payload, and DELETE often will have none as well

Our example REST call is below, along with the returned response:


curl -k -u username:password -X GET

https://InfobloxFqdnOrIPHere/wapi/v1.7/network -d network=10.1.1.0/24

Returns:

HTTP Status Code 200 along with the following content (a JSON payload):


[

   {
       “_ref”: “network/ZG5zLm5ldHdvcmskMTAuMzMuODQuMC8yNC8w:10.1.1.0/24/default”,
       “comment”: “Example Network”,
       “network”: “10.1.1.0/24”,
       “network_view”: “default”
   }
]

So, why use REST?

REST provides a clean way of interacting with multiple systems in multiple formats, without the need for application- and language-specific plugins.

It can be used as the “glue” in task automation from your engine of choice to stitch together links in a chain—such as a build server automatically cutting a standard change in ServiceNow, or a provisioning process querying your IPAM and backup systems to check available capacity before allowing build requests to be approved.

The next post in this series will focus on integrating a provisioning process with ServiceNow in order to automate creation of change requests and CMDB entries, with Incident tickets being created in case of failure as well.