This page contains information about configuring and using the Grid Manager API (application programming interface).

Introduction

IPAM Grid Manager includes a RESTful Web API (WAPI).  The purpose of this page is to help you get started using WAPI, and to make you aware of some important considerations that are specific to the University of Illinois IPAM service.  Please refer to the vendor documentation for a comprehensive API reference.

WAPI vendor documentation is available from https://ipam.illinois.edu/wapidoc/ or published in PDF format.

The current WAPI version is 2.12.3. New client programs should be written to use this version.

Previous WAPI versions still supported include: 1.4.2, 2.2.2, 2.7.3, 2.11.1

API Credentials

All IPAM users (see How do I gain access to IPAM?) also have access to the API.  You must authenticate using your full Active Directory userPrincipalName (typically yournetid@illinois.edu or serviceuser@ad.uillinois.edu, but other variations are also possible).

Using your own credentials is appropriate for direct, interactive use of the API (e.g. command-line utilities) where you can supply your Active Directory password and Multi-Factor Authentication (MFA) at run time.  IPAM is not able to prompt you interactively for a second authentication factor, but you can append a passcode or factor name to your password as documented in https://guide.duo.com/append-mode.

If your application requires unattended access to the IPAM API, you will need to create and authorize a non-person service user:

1. Create an Active Directory user object under your own organizational unit (OU) with a strong, randomly generated password.  We suggest choosing a name longer than 8 characters that begins with your unit or group followed by a dash (e.g. “techsvc-foo”) for easy identification and to avoid conflicting with potential NetIDs; see also Active Directory Naming Conventions.

2. Use Contacts Database to grant the desired permissions to your service user (either directly or via an AD group).

   Note that Contacts Database identifies users by their Active Directory sAMAccountName, a.k.a. “User logon name (Pre-Windows 2000)”, which is different from the userPrincipalName you will use to authenticate to the IPAM API.
3. Non-person service users must be individually exempted from MFA for IPAM by the IPAM service managers.  Contact hostmgr with the Active Directory userPrincipalName of your service user to request this.
4. Verify that you can successfully authenticate to the IPAM API with the Active Directory userPrincipalName of your service user.  If the actual password happens to contain any commas, we suggest appending “,push” as a placeholder so that authentication can succeed on the first try.

Rules of Use

1. Contrary to some of the vendor-provided examples,

   • Always use a hostname (i.e. “ipam.illinois.edu” for production) in the WAPI request URL. Do not use an IP address.

     It is possible that the IP address of the grid master may change from time to time, but the hostname ipam.illinois.edu will always resolve to the current grid master’s IP.

   • DO NOT disable SSL/TLS validation e.g. by passing the “-k” option to curl.
2. Use the “ibapauth” cookie (see Transport and Authentication) when making multiple API requests in the same program invocation, so that IPAM will not have to recheck your credentials (and MFA) for every single request.

3. Keep in mind that the grid master has finite computational resources, and be responsible and considerate in your usage. Do not (for example) write a script that performs lots of intensive API operations and schedule it to run automatically every few minutes.

   If you need to write a recurring API job that could significantly impact the grid master, please talk to us first. We don’t want to have to revoke access to the API.

4. Read and understand Backward Compatibility, and plan your deployments accordingly.

   Best practice: obtain the full WAPI base URL including version (e.g. https://ipam.illinois.edu/wapi/v2.12.3) from one or more configuration parameters rather than hardcoding it directly into your program.

Quick Start

Try a few simple GET requests from the command line using curl:

• Retrieve the singleton Grid object (a simple test to make sure your credentials work):

  curl --user yournetid@illinois.edu -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/grid'

• Again, but also save the returned “ibapauth” cookie to a temporary cookie jar file, and use it to make a subsequent request without having to supply credentials:

  COOKIE_JAR=$(mktemp)
  
  curl --user yournetid@illinois.edu -c ${COOKIE_JAR:?} -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/grid'
  
  curl -b ${COOKIE_JAR:?} -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/grid'
  
  rm ${COOKIE_JAR:?}

  Be sure to consider the security implications of storing the cookie in a file!  Real applications should store it in memory instead (where it cannot be read by other processes).

• List all IPv4 Networks you have permission to see:

  curl --user yournetid@illinois.edu -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/network'

• Again, but include Extensible Attributes (such as Network Name) in the returned data, and limit the result set to 2 objects:

  curl --user yournetid@illinois.edu -X GET \
  'https://ipam.illinois.edu/wapi/v2.12.3/network?_return_fields=network,extattrs&_max_results=2'

• Again, but use paging to iterate through the entire result set, retrieving 2 objects at a time.

  This is a simple example for demonstration purposes.  In practice, results paging is only necessary when your search might return too many objects to retrieve all at once (e.g. > 1000), and you should use a page size on the order of 500 or 1000.

  Initial request:

  curl --user yournetid@illinois.edu -X GET \
  'https://ipam.illinois.edu/wapi/v2.12.3/network?_return_fields=network,extattrs&_max_results=2&_paging=1&_return_as_object=1'

  Subsequent requests:

  curl --user yournetid@illinois.edu -X GET \
  'https://ipam.illinois.edu/wapi/v2.12.3/network?_page_id=789c5590...9c96b659'

  where each new request’s `_page_id` is the value of `next_page_id` returned by the previous request.

The documentation includes sample curl requests for PUT, POST, and DELETE (Examples accessing WAPI using Curl), but many of these examples require permissions that are not given to non-superusers in our environment (e.g. creating Networks).  Try adapting them to other object types, such as a stand-alone A record:

• Use POST to create a new stand-alone A record:

  curl --user yournetid@illinois.edu -X POST 'https://dev.ipam.illinois.edu/wapi/v2.12.3/record:a' \
  -H "Content-Type: application/json" \
  --data '{ "name": "mytestrecord.sandbox.illinois.edu", "ipv4addr": "192.168.0.5", "comment": "WAPI is fun" }'

• Search for the record we just created, and note its object reference (“_ref“) in the output:

  curl --user yournetid@illinois.edu -X GET 'https://dev.ipam.illinois.edu/wapi/v2.12.3/record:a?name=mytestrecord.sandbox.illinois.edu'

• Use PUT to modify the ipv4addr field of the existing record (using the object reference obtained above):

  curl --user yournetid@illinois.edu -X PUT 'https://dev.ipam.illinois.edu/wapi/v2.12.3/record:a/ZG5zLmJp...LjAuMC41' \
  -H "Content-Type: application/json" \
  --data '{ "ipv4addr": "192.168.0.6" }'

Resources

The Infoblox Community site has an article on Getting Started with the Infoblox Web API (WAPI) which you may find helpful, as well as a long list of REST examples (user-contributed) and other searchable content.

Perl

Here are a helper module and a working example script that you can use as a basis for your own programs.  Set environment variable IPAM_WAPI to the desired WAPI base URL (including version) before running the script.

• IPAMUserAgent.pm

  Helper module for IPAM WAPI scripts written in Perl.
  Requires LWP::UserAgent, optionally uses Config::Simple

• add_host_ip.pl

  Uses GET, POST, and PUT requests to either create a new Host record or add an IP to an existing Host record.
  Requires IPAMUserAgent.pm (above), JSON, and NetAddr::IP.

Python

Here are a helper module and a working example script that you can use as a basis for your own programs.  Set environment variable IPAM_WAPI to the desired WAPI base URL (including version) before running the script.

• ipam.py

  Helper module for IPAM WAPI scripts written in Python 3.
  Requires requests (http://docs.python-requests.org)

• add_host_ip.py

  Uses GET, POST, and PUT requests to either create a new Host record or add an IP to an existing Host record.
  Requires ipam.py (above)

Ansible

Ansible provides official Infoblox NIOS modules for many common use cases; see also Ansible’s Infoblox Guide.  Here are a helper playbook and some working example playbooks to get you started; note that these playbooks take extra care to avoid unexpectedly overwriting or deleting an existing record.

Requires infoblox-client (https://infoblox-client.readthedocs.org/)

• ipam-provider.yml

  Helper playbook for IPAM automation using Ansible 2.8+

• add-ipam-host.yml

• delete-ipam-host.yml
• add-ipam-a.yml
• delete-ipam-a.yml
• add-ipam-aaaa.yml
• delete-ipam-aaaa.yml
• add-ipam-cname.yml
• delete-ipam-cname.yml

Deprecated Perl-only API (PAPI)

You may encounter occasional references to a legacy Perl-only API (PAPI) which predated the modern RESTful Web API (WAPI), worked only with Perl, and required specific Infoblox perl modules to be installed on every client system and upgraded in lockstep with the appliance grid.  Use of PAPI at the University of Illinois has been strongly discouraged for many years, and it is now officially deprecated by the vendor as well.  Our only reason for mentioning it here is to forestall confusion in case you encounter the term and wonder what it means.