Skip to content

The definitive list of REST examples

Jump to bottom
Ryan Bolger edited this page Apr 19, 2017 · 37 revisions

Background

This page will attempt to be a "ported" version of the Infoblox community post of the same name using Posh-IBWAPI functions. The original version can be found here: https://community.infoblox.com/t5/API-Integration/The-definitive-list-of-REST-examples/td-p/1214

All examples assume you have already configured common connection settings with Set-IBWAPIConfig. For example:

Set-IBWAPIConfig -host gridmaster.test.com -ver latest -cred (Get-Credential)

Functions generally output zero or more PSCustomObject objects natively parsed from the WAPI's JSON output. In the examples below, these objects may be displayed in their original JSON notation for readability. While trying the examples on your own, it can be helpful to convert your own result objects to JSON as well. For example:

$hosts = Get-IBObject -type record:host
# output the first host result as JSON
$hosts[0] | ConvertTo-Json

The definitive list of REST examples

A common question we are asked is "Do you have some examples of specific REST calls", or "How can I get started with testing the WAPI?".

The API docs are good if you need the technical details, but this post hopes to address the overall fundamentals.

The Basics

  • use Get-IBObject to get/search
  • use New-IBObject to add
  • use Set-IBObject to modify
  • use Remove-IBObject to remove

If you want to modify an object, you have to use a Get-IBObject to read it first. This will give you the _ref (among other base fields), which you will need in order to update that object.

# Get a specific host by name (case-insensitive)
$testhost = Get-IBObject -type record:host -filters 'name:=test_host.test.com'

# $testhost contains
{
    "_ref":  "record:host/ZG5zLmhvc3QkLjEubmV0LmR2b2x2ZS5leHRucw:test_host.test.com/default",
    "ipv4addrs":  [
                      {
                          "_ref":  "record:host_ipv4addr/ZG5zLmhvc3RfYWRkcmVzcyQuMS5uZXQuZHZvbHZlLmV4dG5zLjEwLjE3LjYuNC4:192.168.0.1/test_host.test.com/default",
                          "configure_for_dhcp":  false,
                          "host":  "test_host.test.com",
                          "ipv4addr":  "1.1.1.1"
                      }
                  ],
    "name":  "test_host.test.com",
    "view":  "default"
}

NOTE: There is currently no way to return all available fields for a given object type. You have to specify any non-base fields explicitly using -ReturnFields 'field1','field2','fieldX'. Also, using -ReturnFields will prevent the base fields from being returned unless you explicitly include them or also use -ReturnBaseFields.

There are two different ways to modify the host you just queried. They involve slightly different ways of calling Set-IBObject. The easiest, particularly if you're making the same change to multiple objects, is usually to just pipe the variable to Set-IBObject and provide a template for the changes with -TemplateObject. This works because Set-IBObject knows how to pull the _ref field out of the pipelined object and use it for -ObjectRef:

# create a template to change the IP address
$template = @{ipv4addrs=@(${ipv4addr='1.1.1.2'})}

# save the change
$testhost | Set-IBObject -template $template

# this also works when you only have a copy of the _ref string
Set-IBObject -ref 'record:host/ZG5zLmhvc3QkLjEubmV0LmR2b2x2ZS5leHRucw' -template $template

The second way involves modifying the variable and then piping it to Set-IBObject by itself. This has a tendency to be more difficult because read-only fields in the original variable need to be removed or an error will be thrown. It can also be more tedious to add fields if the original variable doesn't contain the fields you want to edit. However, this way can also be easier if you're changing many objects in a more algorithmic way; such as modifying a set of hostnames using string replacement.

# remove the read-only 'host' field from the nested 'record:host_ipv4addr' object
$testhost.ipv4addrs[0].PSObject.Properties.Remove('host')

# change the IP address
$testhost.ipv4addrs[0].ipv4addr = '1.1.1.2'

# add a comment
$testhost | Add-Member @{comment='my test host'}

# save the change
$testhost | Set-IBObject

Search for HOST by name

# case-sensitive exact match using '='
Get-IBObject -type record:host -filters 'name=my.fqdn.org'

# case-insensitive exact match using ':=' (Requires WAPI 1.4+)
Get-IBObject -type record:host -filters 'name:=my.fqdn.org'

# case-sensitive Regex partial match using '~='
Get-IBObject -type record:host -filters 'name~=my'

# case-insensitive Regex partial match using ':~=' (Requires WAPI 1.4+)
Get-IBObject -type record:host -filters 'name:~=my'

Search for FixedAddress by MAC

# return base fields + mac
Get-IBObject -type fixedaddress -filters 'mac=aa:bb:cc:11:22:33' -fields 'mac' -base

Search for objects associated with a specific IP address

$ipObj = Get-IBObject -type ipv4address -filters 'status=USED','ip_address=1.1.1.1'

# the object references are stored in the 'objects' field, but we can
# also query for additional information
$ipObj | select -expand objects | Get-IBObject

# just list the names associated with that IP
$ipObj | select -expand names

Add a HOST

# create the object variable
$newhost = @{ name='wapi.test.org'; ipv4addrs=@( @{ ipv4addr='1.1.1.21' } ) }

# Note: `configure_for_dns` defaults to $true which means the 'test.org' DNS zone for this
# host must be managed by Infoblox for the call to succeed. Otherwise, you must set configure_for_dns=$false.

# Note: the network containing the specified IP must also be managed by Infoblox for the call to succeed.

# create the host
$newhost | New-IBObject -type record:host

Delete a HOST

# search for the host we want to delete
$delHost = Get-IBObject -type record:host -filters 'name=wapi.test.org'

# delete it
$delHost | Remove-IBObject

# or delete it directly using an already known object reference
Remove-IBOBject -ref 'record:host/ZG5zLmhvc3QkLm5vbl9ETlNfaG'

Update a host, or change the IP address

(See the examples in The Basics)

Add/Remove IP addresses from a host without altering the original list

# add with `ipv4addrs+` in your change template
$template = @{ 'ipv4addrs+' = @( @{ ipv4addr='2.2.2.22' }, @{ ipv4addr='4.4.4.24' } ) }

# save the change using a known object reference
Set-IBObject -ref 'record:host/ZG5zLmhvc3QkLl9kZWZhdWx0Lm9yZy5naC53YXBp' -template $template

# remove with `ipv4addrs-' in your change template
$template = @{ 'ipv4addrs-' = @( @{ ipv4addr='2.2.2.22' } ) }

# save the change using an existing $myhost variable returned by Get-IBObject
$myhost | Set-IBObject -template $template

Add a HOST with next_available IP address from a network

# create the object variable
$newhost = @{ name='wapi.test.org'; ipv4addrs=@( @{ ipv4addr='func:nextavailableip:10.1.1.0/24' } ) }

# 'func:' syntax also supports these forms:
# func:nextavailableip:network/ZG54dfgsrDFEFfsfsLzA:10.0.0.0/8/default
# func:nextavailableip:10.0.0.0/8
# func:nextavailableip:10.0.0.0/8,external
# func:nextavailableip:10.0.0.3-10.0.0.10

# OR you can use the longhand form
$newhost = @{ name='wapi.test.org'; ipv4addrs=@( @{ ipv4addr=@{} } ) }
$newhost.ipv4addrs[0].ipv4addr._function = 'next_available_ip'
$newhost.ipv4addrs[0].ipv4addr._object_field = 'value'
$newhost.ipv4addrs[0].ipv4addr._object = '10.1.1.0/24'
$newhost.ipv4addrs[0].ipv4addr._parameters = @{ num=1; exclude=@('10.1.1.50','10.1.1.60') }

# create the host
$newhost | New-IBObject -type record:host

Add a HOST with next_available IP address from a network using a complex search (e.g Extensible Attributes)

# This is similar to the previous example using longhand form
# But you need to pass the search criteria in the `_object_parameters` field
# Note also that `_object` changes from a reference to a type
$newhost = @{ name='wapi.test.org'; ipv4addrs=@( @{ ipv4addr=@{} } ) }
$newhost.ipv4addrs[0].ipv4addr._function = 'next_available_ip'
$newhost.ipv4addrs[0].ipv4addr._object_field = 'value'
$newhost.ipv4addrs[0].ipv4addr._object = 'network'
$newhost.ipv4addrs[0].ipv4addr._object_parameters = @{ '*Site'='Santa Clara' }
$newhost.ipv4addrs[0].ipv4addr._parameters = @{ num=1; exclude=@('10.1.1.50','10.1.1.60') }

# create the host
$newhost | New-IBObject -type record:host

Add a HOST with a fixed address

# basically the same as adding a normal host, but include a mac address
$newhost = @{ name='wapi.test.org'; ipv4addrs=@( @{} ) }
$newhost.ipv4addrs[0].ipv4addr = '1.1.1.21'
$newhost.ipv4addrs[0].mac = 'aa:bb:cc:11:22:21'

# create the host
$newhost | New-IBObject -type record:host

Add a Fixed address

New-IBObject -type fixedaddress -IBObject @{ipv4addr='1.1.1.21';mac='aa:bb:cc:11:22:21'}

Add a Fixed address Reservation

New-IBObject -type fixedaddress -IBObject @{ipv4addr='1.1.1.21';mac='00:00:00:00:00:00'}
Clone this wiki locally