Deans Blog

In previous posts I have discussed phpIPAM which is an open-source IP address management application (IPAM). In this blog, I will discuss interacting with the REST API (version 2.0) to programatically create new IP addresses for a specific subnet.

For the purpose of this article, I will be using the Postman REST client to submit requests and interact with the API and the following variables reference values you will need to replace for your environment if you are replicating the process:

Variable	Description	Example
{appId}	API application identifier	dean
{subnet}	Subnet in CIDR format	10.10.1.0/24
{subnetId}	Id of subnet address	3

In order to use the API you will need to authenticate (required for none and SSL) with the username and password and use the HTTP authentication header.

If authentication is successful, you will receive the token to include in the token header for subsequent requests to the API. Also, you will receive the expiry of the token which is set to six hours by default. For each subsequent request to the API the expiration time for the token is reset.

POST api/{appId}/user/

By specifying the authorization type as ‘Basic Authentication’ and specifying a username and password this will generate the required Authorization header for the request by encoding the values to a base64 encoded string.

A status code of ‘200’ will be returned if the authentication attempt is successful, the required token value will also be returned in the response body with the expiration date.

{
  "code": 200,
  "success": true,
  "data": {
    "token": ".Cy9kljLjG=WIt9i.gmA%tUY",
    "expires": "2016-12-03 13:13:06"
  },
  "time": 5.036
}

Once the token has been received the cool stuff can now begin and we can start to interact with the API. In the next example, I am going to use a common use case for phpIPAM. I need to request the next available free IP address for a specified subnet and allocate this to a host.

So, lets look at the method we need to use to create a new address from a specified subnet from the addresses section of the documentation

POST  /api/{appId}/addresses/first_free/{subnetId}/

An alternative GET method exists, however whilst this will return the next available IP address it will not create the object for the new IP address in the database.

GET /api/{appId}/addresses/first_free/subnet

From the POST method we need to provide the Id of the subnet we require to create an IP address, therefore prior to invoking the request we need to return this value, by referencing the subnets section of the documentation, the following can be used by providing the subnet in CIDR format.

GET /api/{appId}/subnets/cidr/{subnet}/

In this example I am searching for the subnet containing the CIDR format 10.10.1.0/24. From the below response body we can retrieve the subnet Id from the data[0].id element and in this example, the subnet Id for the subnet 10.10.1.0/24 is ‘3’. As you can see from the headers section, I am now specifying the ‘token’ header previously returned from the successful authorization.

{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "3",
      "subnet": "10.10.1.0",
      "mask": "24",
      "sectionId": "1",
      "description": "Customer 1",
      "linked_subnet": null,
      "firewallAddressObject": null,
      "vrfId": "0",
      "masterSubnetId": "2",
      "allowRequests": "1",
      "vlanId": "0",
      "showName": "1",
      "device": "0",
      "permissions": "{\"3\":\"1\",\"2\":\"2\"}",
      "pingSubnet": "0",
      "discoverSubnet": "0",
      "DNSrecursive": "0",
      "DNSrecords": "0",
      "nameserverId": "0",
      "scanAgent": null,
      "isFolder": "0",
      "isFull": "0",
      "tag": "2",
      "threshold": "0",
      "location": null,
      "editDate": null,
      "links": [
        {
          "rel": "self",
          "href": "/api/dean/subnets/3/"
        }
      ]
    }
  ],
  "time": 0.002
}

Now, lets return to creating a new address in the specified subnet with the below request to create a new address in the subnet from the POST method. From the response body, the data element contains the IP address ‘10.10.1.26’ created for the subnet.

POST  /api/{appId}/addresses/first_free/3/

{
  "code": 201,
  "success": true,
  "message": "Address created",
  "id": "34",
  "data": "10.10.1.26",
  "time": 0.015
}

We can also include a request body in the POST method to include information for creating the new IP address in the subnet. The supported parameters are listed for the address controller in the addresses section. In this example, I have included the hostname, description and owner values for the request.

As you can see if you have read the provided API documentation, I am only touching the surface of what is possible by programmatically interacting with the API and how you can leverage this in your automation and orchestration practices.