API

grid.ip.list

From GoGrid

1 Request
2 Response

This call will list the ips available to in your grid. This method follows a common list pattern but has added filter capabilities. With filtering you can see all, unassigned, public, or private ips.

Request

URL

https://api.gogrid.com/api/grid/ip/list

Role Based Access Control Permissions

Super User

System User

Billing User

Read Only User

Input Request Query Parameters

Required

Name

Version

Type

Description

Required

api_key

1.0

string

An API Key generated by GoGrid.

sig

1.0

string

An MD5 Signature that signs each and every API request. Instructions on how to generate this signature can be found here.

1.0

string

The version of the API. For more information, see API Versions.

For version 1.3, set parameter to 1.3

Optional

num_items

1.0

int

The number of items to return. Specifying this value will effectively paginate the results of a list call into a number of pages with this number of items per page. This makes it easier and faster to access large lists. If not specified, result will not be paginated.

page

1.0

int

The page index to return for paginated results, indexed from 0, so a value of 0 will return the first available page, 1 will return the second page and so forth. This parameter is ignored if num_items is not specified.

ip.state

1.1

string

The state to filter on. int or string representing the state option's id or name respectively.

If no value is set for this parameter, all states will be included in the query.
To list ip.state values, call common.lookup.list with lookup set to ip.state

ip.type

1.1

string

The type to filter on. int or string representing the type option's id or name respectively.

If no value is set for this parameter, all types will be included in the query.
To list ip.type values, call common.lookup.list with lookup set to ip.type

Sample Request

To list unassigned, public ips:

https://api.gogrid.com/api/grid/ip/list
  ?id=203923
  &ip.state=Unassigned
  &ip.type=Public
  ... auth parameters...

Response

A common list response of ips. The list is a full of partial list of your ips in the system based on your filtering criteria.

JSON Response

{
    "list": [
        {
            "id": 497,
            "ip": "208.113.75.240",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is reserved or in use",
                "id": 2,
                "name": "Assigned",
                "object": "option"
            },
            "subnet": "208.113.75.240/255.255.255.240"
        },
        {
            "id": 498,
            "ip": "208.113.75.241",
            "object": "ip",
            "public": true,
            "state": {
                "description": "IP is reserved or in use",
                "id": 2,
                "name": "Assigned",
                "object": "option"
            },
            "subnet": "208.113.75.240/255.255.255.240"
        }
    ],
    "method": "/grid/ip/list",
    "status": "success",
    "summary": {
        "numpages": 136,
        "returned": 2,
        "start": 0,
        "total": 272
    }
}

XML Response

<gogrid>
  <response method="/grid/ip/list" status="success">
    <summary total="272" start="0" numpages="68" returned="4"/>
    <list>
      <object name="ip">
        <attribute name="id">497</attribute>
        <attribute name="ip">208.113.75.240</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">Assigned</attribute>
            <attribute name="description">IP is reserved or in use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.75.240/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
      </object>
      <object name="ip">
        <attribute name="id">498</attribute>
        <attribute name="ip">208.113.75.241</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">2</attribute>
            <attribute name="name">Assigned</attribute>
            <attribute name="description">IP is reserved or in use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.75.240/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
      </object>
      <object name="ip">
        <attribute name="id">499</attribute>
        <attribute name="ip">208.113.75.242</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.75.240/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
      </object>
      <object name="ip">
        <attribute name="id">500</attribute>
        <attribute name="ip">208.113.75.243</attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Unassigned</attribute>
            <attribute name="description">IP is available to use</attribute>
          </object>
        </attribute>
        <attribute name="subnet">208.113.75.240/255.255.255.240</attribute>
        <attribute name="public">true</attribute>
      </object>
    </list>
  </response>
</gogrid>

CSV Response

# SUCCESS, /grid/ip/list, TOTAL, 272, NUMPAGES, 68, START, 0, RETURNED, 4
# id,ip,state.id,state.name,state.description,subnet,public
497,208.113.75.240,2,Assigned,IP is reserved or in use,208.113.75.240/255.255.255.240,true
498,208.113.75.241,2,Assigned,IP is reserved or in use,208.113.75.240/255.255.255.240,true
499,208.113.75.242,1,Unassigned,IP is available to use,208.113.75.240/255.255.255.240,true
500,208.113.75.243,1,Unassigned,IP is available to use,208.113.75.240/255.255.255.240,true

Error Codes

Status

Code

Description

400

IllegalArgumentException

Any problems with input parameters will generate an IllegalArgumentException.

401

Unauthorized

This error code will occur when the role tied to the API Key in your request has the wrong Access Controls.

403

Authentication Failed

This error code will occur when your request is not properly signed. Make sure your have a valid API key and secret and that you are properly generating a request signature. Ensure that the clock on the computer from which you are making the request is synchronized woth the GoGrid API Server.

404

Not Found

This error will occur if you have specified a method that does not exist or any other URL does not exists on the API Server.

500

UnexpectedError

These types of errors indicate an internal system problem. Depending on the severity of the error and whether not it is blocking your development, report the error to GoGrid support by emailing the response to apisupport@gogrid.com.

Retrieved from "http://wiki.gogrid.com/wiki/index.php/API:grid.ip.list"