Collins

The Collins API

Getting RESTful with your assets

Overview

Collins API design principles and conventions

Design

The initial design goal was that the entire API should be usable from the command line, even with netcat. To that end, basic auth is used for HTTP authentication, and curl is an adequate client interface as long as you're inclined. There are no plans to ever use OAuth or a similar authentication mechanism.

The collins API has two nice features. First, it is as RESTful as it could be without being an ass. Status codes are used to indicate what happened uniformly, appropriate HTTP methods (PUT, GET, etc) for each endpoint, plural/singular endpoints as you would expect, etc. Second, you can request the output for any API endpoint as plain text, JSON, or bash (sh compatible).

Conventions

Basics

  • Basic auth is used for all HTTP endpoints
  • A URI describes a resource
  • PUT creates a resource
  • POST modifies a resource
  • DELETE kills a resource

Status Codes

Note that some status codes listed below won't be listed in the documentation. Status codes 400, 401, 405 and 500 will never be documented. You will always get an HTTP 400 if there is a bad parameter, you will always get an HTTP 401 if you fail to authenticate, you will always get an HTTP 405 if you use the wrong verb, and you will always get an HTTP 500 if there is an internal server error. I am stating this once to avoid restating it dozens of times in the internal docs.

CodeUse
200Normal operation, expect this
201Resource created, all PUT calls should return this on success
202Resource accepted for deletion
400Bad input found, modify your request and try again
401You failed to authenticate successfully, retry using different credentials
403You do not have appropriate privileges to perform the specified operation
404Resource not found - this is a normalish response code
405Unsupported HTTP method - modify request before retry
409Performing the operation would have created a conflict (duplicate IP, duplicate name, etc)
429You are being rate limited, slow down
500An internal error occurred, you should probably try again
501You are trying to perform an operation that the system is not configured for
504If multicollins or the provision plugins are configured and a timeout occurs interacting with a remote service

Response Formats

Use the Accept header to specify the output format. JSON is the default output format and in general the best to use. However, every API endpoint has support for plain text, bash, and JSON output. The recognized accept headers for the API are:

  • text/plain
  • application/json
  • text/x-shellscript

The text/x-shellscript endpoint will modify keys to make them valid POSIX variables. Specifically, if a key starts with a special character or digit, an underscore will be prepended to the key. Also, any special characters in a key will be replaced with underscores.

API Versioning

Collins supports API versioning via the accept header. This allows developers to make breaking changes to the API and continue to have old clients work. This is implemented but I'll leave this to Dan to document.

Pagination

Paginated result sets always provide results in a standard format. Paginated results also always included a header with the same pagination information that can be found in the result set. The headers with pagination information are:

  • X-Pagination-PreviousPage
  • X-Pagination-CurrentPage
  • X-Pagination-NextPage
  • X-Pagination-TotalResults

The JSON output format will return an object with a Pagination key and an object value. The pagination object has the following keys: PreviousPage, CurrentPage, NextPage, Total Results.

If an API endpoint can be paginated it will be annotated with a Paginated marker. Paginated API endpoints accept the following parameters:

NameTypeDescription
page Option[Integer] Defaults to zero, indexed from zero. The page of results that you want.
size Option[Integer] Number of results to return. Generally defaults to 10.
sort Option[String] Valid values are "ASC" or "DESC". Generally defaults to "DESC".

Documentation Conventions

If a URI contains a colon (:) followed by text, this is a required part of the URI. This is typically used for specifying the resource you are interacting with. For instance if a URI is documented as /api/foo/:bar then :bar is a variable that is specified as part of the URI.

Asset API

CRUD operations for your assets

Overview

The Asset API is the primary interface for manipulating Collins assets. The operations that can be performed is somewhat dependent on the status of an asset (for instance, you can not upload new LSHW data to an asset that is Allocated). For more information on asset states and status see the Status & State document.

Asset Create
DescriptionCreate a new asset
RequestPUT /api/asset/:tag
Permissioncontrollers.AssetApi.createAsset
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes) and unique
generate_ipmi Option[Boolean] True or false. Defaults to true if asset_type is SERVER_NODE
status Option[Status] A valid status, if specified. Defaults to Incomplete.
type Option[AssetType] One of SERVER_NODE, SERVER_CHASSIS, RACK, SWITCH, ROUTER, POWER_CIRCUIT or POWER_STRIP. Defaults to SERVER_NODE. If additional asset types are added to the database, they can also be specified.
Response Codes
CodeReason
201 Asset was successfully created
409 Asset with specified tag already exists
collins-shell asset create --tag=TAG [--ipmi=(true|false) --status=STATUS --type=TYPE]
curl --basic -u collins:collins -X PUT http://localhost:9000/api/asset/tumblrtag30
JSON Response 
{
  "status": "success:created",
  "data": {
    "ASSET": {
      "ID": 2,
      "TAG": "tumblrtag30",
      "STATE": null,
      "STATUS": "Incomplete",
      "TYPE": "Server Node",
      "CREATED": "2012-09-16T18:30:55",
      "UPDATED": null,
      "DELETED": null
    },
    "IPMI": {
      "ASSET_ID": 2,
      "ASSET_TAG": "tumblrtag30",
      "IPMI_USERNAME": "root",
      "IPMI_PASSWORD": "WqbXjuqWd5MZ01fD",
      "IPMI_GATEWAY": "172.16.32.1",
      "IPMI_ADDRESS": "172.16.32.20",
      "IPMI_NETMASK": "255.255.240.0",
      "ID": 2
    }
  }
}
Bash Response 
ASSET_ID=3;
ASSET_CREATED="2012-09-16T18:42:21";
ASSET_TAG="tumblrtag31";
ASSET_STATUS="Incomplete";
ASSET_DELETED=;
ASSET_UPDATED=;
ASSET_STATE=;
ASSET_TYPE="Server Node";
IPMI_IPMI_USERNAME="root";
IPMI_ID=3;
IPMI_IPMI_ADDRESS="172.16.32.21";
IPMI_IPMI_NETMASK="255.255.240.0";
IPMI_ASSET_ID=3;
IPMI_ASSET_TAG="tumblrtag31";
IPMI_IPMI_GATEWAY="172.16.32.1";
IPMI_IPMI_PASSWORD="zqkWfV9baxlrJa5Y";
Text Response 
ASSET
        ID      4
        CREATED 2012-09-16T18:43:35
        TAG     tumblrtag32
        STATUS  Incomplete
        DELETED null
        UPDATED null
        STATE   null
        TYPE    Server Node
IPMI
        IPMI_USERNAME   root
        ID      4
        IPMI_ADDRESS    172.16.32.22
        IPMI_NETMASK    255.255.240.0
        ASSET_ID        4
        ASSET_TAG       tumblrtag32
        IPMI_GATEWAY    172.16.32.1
        IPMI_PASSWORD   BCGHWinJlme9g9x0

Asset Update
DescriptionUpdate an asset
RequestPOST /api/asset/:tag
Permissioncontrollers.AssetApi.updateAsset
Parameters
NameTypeDescription
lshw String Only accepted when the asset is Incomplete, Maintenance, or states specified in allowedServerUpdateStatuses. Should be the XML output from running the lshw command on the asset.
lldp String Only accepted when the asset is Incomplete, Maintenance, or states specified in allowedServerUpdateStatuses. Should be the XML output from running the lldp command on the asset.
groupId Option[Int] The dimension of the specified tag. Can only be combined with attribute
attribute Option[String] Specified a key/value pair to associated with the asset where the key isn't a managed tag. The key/value pair should be formatted as keyname;valuename
CHASSIS_TAG Option[String] Only accepted for Incomplete assets during the intake phase, Maintenance, or states specified in allowedServerUpdateStatuses.
RACK_POSITION Option[String] Only accepted for New assets during the web based intake process
POWER_PORT_{S} Option[String] Only accepted for New assets during the web based intake process. The parameters allowed here depend on the power configuration
Response Codes
CodeReason
200 Asset updated successfully
404 The specified asset was not found
collins-shell asset set_attribute TAG_NAME TAG_VALUE --tag=TAG 
curl --basic -u collins:collins \
  --data-urlencode "lldp@./test/resources/lldpctl-two-nic.xml" \
  --data-urlencode "lshw@./test/resources/lshw-basic.xml" \
  --data-urlencode 'CHASSIS_TAG=chassistag123' \
  --data-urlencode 'attribute=NODECLASS;web' \
  http://localhost:9000/api/asset/tumblrtag30
You should notice if you run the example that the asset status automatically changes from Incomplete to New. This is part of the automatic lifecycle management from Incomplete and New assets.
JSON Response 
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}
Bash Response 
SUCCESS=true;
Text Response 
SUCCESS true

Asset Update Status
DescriptionUpdate the status or state of an asset
RequestPOST /api/asset/:tag/status
Permissioncontrollers.AssetApi.updateAssetStatus
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes) and unique
reason String The reason for the status or state change
status Option[Status] The new status of the specified asset
state Option[State] The new state of the specified asset
Response Codes
CodeReason
200 State and/or status was successfully updated
400 Neither state nor status specified, missing reason, or invalid status/state
409 Update would cause a conflict between state and status
collins-shell asset set_status --reason=REASON [--state=STATE --status=STATUS]
curl --basic -u collins:collins \
-d status=Unallocated \
-d state=Running \
-d reason='Ready for action' \
http://localhost:9000/api/asset/tumblrtag30/status
JSON Response 
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Asset Get
DescriptionGet an asset by tag
RequestGET /api/asset/:tag
Permissioncontrollers.AssetApi.getAsset
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes) and unique
Response Codes
CodeReason
200 Asset was found
404 Asset could not be found
collins-shell asset get TAG
curl --basic -u collins:collins http://localhost:9000/api/asset/tumblrtag30
JSON Response 
{
  "status": "success:ok",
  "data": {
    "ASSET": {
      "ID": 2,
      "TAG": "tumblrtag30",
      "STATE": {
        "ID": 1,
        "STATUS": null,
        "NAME": "NEW",
        "LABEL": "New",
        "DESCRIPTION": "A service in this state is inactive. It does minimal work and consumes minimal resources."
      },
      "STATUS": "New",
      "TYPE": "Server Node",
      "CREATED": "2012-09-16T18:30:55",
      "UPDATED": "2012-09-16T18:46:41",
      "DELETED": null
    },
    "HARDWARE": {
      "CPU": [
        {
          "CORES": 6,
          "THREADS": 6,
          "SPEED_GHZ": 2.3,
          "DESCRIPTION": "AMD Opteron(tm) Processor 4174 HE Hynix Semiconductor (Hyundai Electronics)",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "CORES": 6,
          "THREADS": 6,
          "SPEED_GHZ": 2.3,
          "DESCRIPTION": "AMD Opteron(tm) Processor 4174 HE Hynix Semiconductor (Hyundai Electronics)",
          "PRODUCT": "",
          "VENDOR": ""
        }
      ],
      "MEMORY": [
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 0,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 1,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 8589934592,
          "SIZE_S": "8589934592",
          "SIZE_HUMAN": "8.00 GB",
          "BANK": 2,
          "DESCRIPTION": "DIMM DDR3 Synchronous 1333 MHz (0.8 ns) - Hyundai HMT31GR7BFR4A-H9",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 3,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 4,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 8589934592,
          "SIZE_S": "8589934592",
          "SIZE_HUMAN": "8.00 GB",
          "BANK": 5,
          "DESCRIPTION": "DIMM DDR3 Synchronous 1333 MHz (0.8 ns) - Hyundai HMT31GR7BFR4A-H9",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 6,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 7,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 8589934592,
          "SIZE_S": "8589934592",
          "SIZE_HUMAN": "8.00 GB",
          "BANK": 8,
          "DESCRIPTION": "DIMM DDR3 Synchronous 1333 MHz (0.8 ns) - Hyundai HMT31GR7BFR4A-H9",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 9,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 0,
          "SIZE_S": "0",
          "SIZE_HUMAN": "0 Bytes",
          "BANK": 10,
          "DESCRIPTION": "Empty Memory Bank",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 8589934592,
          "SIZE_S": "8589934592",
          "SIZE_HUMAN": "8.00 GB",
          "BANK": 11,
          "DESCRIPTION": "DIMM DDR3 Synchronous 1333 MHz (0.8 ns) - Hyundai HMT31GR7BFR4A-H9",
          "PRODUCT": "",
          "VENDOR": ""
        }
      ],
      "NIC": [
        {
          "SPEED": 1000000000,
          "SPEED_S": "1000000000",
          "SPEED_HUMAN": "1.00 Gb",
          "MAC_ADDRESS": "e8:9a:8f:23:15:72",
          "DESCRIPTION": "82576 Gigabit Network Connection - Intel Corporation",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SPEED": 1000000000,
          "SPEED_S": "1000000000",
          "SPEED_HUMAN": "1.00 Gb",
          "MAC_ADDRESS": "e8:9a:8f:23:15:72",
          "DESCRIPTION": "82576 Gigabit Network Connection - Intel Corporation",
          "PRODUCT": "",
          "VENDOR": ""
        }
      ],
      "DISK": [
        {
          "SIZE": 1000204886016,
          "SIZE_S": "1000204886016",
          "SIZE_HUMAN": "931.51 GB",
          "TYPE": "SCSI",
          "DESCRIPTION": "Seagate ST91000640NS",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 1000204886016,
          "SIZE_S": "1000204886016",
          "SIZE_HUMAN": "931.51 GB",
          "TYPE": "SCSI",
          "DESCRIPTION": "Seagate ST91000640NS",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 1000204886016,
          "SIZE_S": "1000204886016",
          "SIZE_HUMAN": "931.51 GB",
          "TYPE": "SCSI",
          "DESCRIPTION": "Seagate ST91000640NS",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 1000204886016,
          "SIZE_S": "1000204886016",
          "SIZE_HUMAN": "931.51 GB",
          "TYPE": "SCSI",
          "DESCRIPTION": "Seagate ST91000640NS",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 1000204886016,
          "SIZE_S": "1000204886016",
          "SIZE_HUMAN": "931.51 GB",
          "TYPE": "SCSI",
          "DESCRIPTION": "Seagate ST91000640NS",
          "PRODUCT": "",
          "VENDOR": ""
        },
        {
          "SIZE": 1000204886016,
          "SIZE_S": "1000204886016",
          "SIZE_HUMAN": "931.51 GB",
          "TYPE": "SCSI",
          "DESCRIPTION": "Seagate ST91000640NS",
          "PRODUCT": "",
          "VENDOR": ""
        }
      ]
    },
    "LLDP": {
      "INTERFACES": [
        {
          "NAME": "eth0",
          "CHASSIS": {
            "NAME": "core01.dfw01",
            "ID": {
              "TYPE": "mac",
              "VALUE": "78:19:f7:88:60:c0"
            },
            "DESCRIPTION": "Juniper Networks, Inc. ex4500-40f , version 11.1S1 Build date: 2011-04-21 08:03:12 UTC "
          },
          "PORT": {
            "ID": {
              "TYPE": "local",
              "VALUE": "608"
            },
            "DESCRIPTION": "ge-0\/0\/3.0"
          },
          "VLANS": [
            {
              "ID": 106,
              "NAME": "DFW-LOGGING"
            }
          ]
        },
        {
          "NAME": "eth1",
          "CHASSIS": {
            "NAME": "core02.dfw01",
            "ID": {
              "TYPE": "mac",
              "VALUE": "5c:5e:ab:68:a5:80"
            },
            "DESCRIPTION": "Juniper Networks, Inc. ex4500-40f , version 11.1R1.10 Build date: 2011-03-16 08:17:03 UTC "
          },
          "PORT": {
            "ID": {
              "TYPE": "local",
              "VALUE": "608"
            },
            "DESCRIPTION": "ge-0\/0\/3.0"
          },
          "VLANS": [
            {
              "ID": 106,
              "NAME": "DFW-LOGGING"
            }
          ]
        }
      ]
    },
    "IPMI": {
      "ASSET_ID": 2,
      "ASSET_TAG": "tumblrtag30",
      "IPMI_USERNAME": "root",
      "IPMI_PASSWORD": "WqbXjuqWd5MZ01fD",
      "IPMI_GATEWAY": "172.16.32.1",
      "IPMI_ADDRESS": "172.16.32.20",
      "IPMI_NETMASK": "255.255.240.0",
      "ID": 2
    },
    "ADDRESSES": [
      
    ],
    "POWER": [
      {
        "UNIT_ID": 0,
        "UNITS": [
          {
            "KEY": "POWER_PORT_A",
            "VALUE": "plug a",
            "TYPE": "POWER_PORT",
            "LABEL": "Plug Strip A",
            "POSITION": 0,
            "IS_REQUIRED": true,
            "UNIQUE": true
          },
          {
            "KEY": "POWER_OUTLET_A",
            "VALUE": "outlet a",
            "TYPE": "POWER_OUTLET",
            "LABEL": "Outlet A",
            "POSITION": 1,
            "IS_REQUIRED": true,
            "UNIQUE": false
          }
        ]
      },
      {
        "UNIT_ID": 1,
        "UNITS": [
          {
            "KEY": "POWER_PORT_B",
            "VALUE": "plug b",
            "TYPE": "POWER_PORT",
            "LABEL": "Plug Strip B",
            "POSITION": 0,
            "IS_REQUIRED": true,
            "UNIQUE": true
          },
          {
            "KEY": "POWER_OUTLET_B",
            "VALUE": "outlet b",
            "TYPE": "POWER_OUTLET",
            "LABEL": "Outlet B",
            "POSITION": 1,
            "IS_REQUIRED": true,
            "UNIQUE": false
          }
        ]
      }
    ],
    "ATTRIBS": {
      "0": {
        "DISK_STORAGE_TOTAL": "6001229316096",
        "NODECLASS": "web",
        "CHASSIS_TAG": "chassistag123"
      }
    }
  }
}

Asset Find
DescriptionFind specified assets
RequestGET /api/assets
Permissioncontrollers.AssetApi.getAssets
Parameters Paginated
NameTypeDescription
details Option[Boolean] True to return full assets, false to return partials. Defaults to false.
remoteLookup Option[Boolean] True to search remote datacenters as well. See the MultiCollins documentation.
operation Option[String] "AND" or "OR", defaults to "OR".
type Option[AssetType] A valid asset type (e.g. SERVER_NODE)
status Option[Status] A valid asset status (e.g. Unallocated)
state Option[State] A valid asset state (e.g. RUNNING)
createdBefore Option[DateTime] ISO8601 formatted
createdAfter Option[DateTime] ISO8601 formatted
updatedBefore Option[DateTime] ISO8601 formatted
updatedAfter Option[DateTime] ISO8601 formatted
attribute Option[String] Specified as tagname;tagvalue. tagname can be a reserved tag such as CPU_COUNT, MEMORY_SIZE_BYTES, etc. Leave tagvalue blank to find assets missing a particular attribute.
Response Codes
CodeReason
200 Zero or more assets successfully found
collins-shell asset find --selector=NODECLASS:web status:Unallocated
curl --basic -u collins:collins 'http://localhost:9000/api/assets?attribute=NODECLASS%3Bweb&status=Unallocated'
JSON Response 
{
  "status": "success:ok",
  "data": {
    "Pagination": {
      "PreviousPage": 0,
      "CurrentPage": 0,
      "NextPage": 0,
      "TotalResults": 3
    },
    "Data": [
      {
        "ID": 4,
        "TAG": "tumblrtag32",
        "STATE": {
          "ID": 3,
          "STATUS": null,
          "NAME": "RUNNING",
          "LABEL": "Running",
          "DESCRIPTION": "A service in this state is operational."
        },
        "STATUS": "Unallocated",
        "TYPE": "Server Node",
        "CREATED": "2012-09-16T19:49:31",
        "UPDATED": "2012-09-16T19:50:05",
        "DELETED": null
      },
      {
        "ID": 2,
        "TAG": "tumblrtag30",
        "STATE": {
          "ID": 3,
          "STATUS": null,
          "NAME": "RUNNING",
          "LABEL": "Running",
          "DESCRIPTION": "A service in this state is operational."
        },
        "STATUS": "Unallocated",
        "TYPE": "Server Node",
        "CREATED": "2012-09-16T19:49:24",
        "UPDATED": "2012-09-16T19:49:57",
        "DELETED": null
      },
      {
        "ID": 3,
        "TAG": "tumblrtag31",
        "STATE": {
          "ID": 3,
          "STATUS": null,
          "NAME": "RUNNING",
          "LABEL": "Running",
          "DESCRIPTION": "A service in this state is operational."
        },
        "STATUS": "Unallocated",
        "TYPE": "Server Node",
        "CREATED": "2012-09-16T19:49:28",
        "UPDATED": "2012-09-16T19:50:02",
        "DELETED": null
      }
    ]
  }
}

Asset Find Similar
DescriptionFind assets similar to another
RequestGET /api/asset/:tag/similar
Permissioncontrollers.AssetApi.getAssets
Note This depends on having a proper nodeclassifer setup. See the nodeclassifier section of the configuration documentation.
Parameters Paginated
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes) and unique
Response Codes
CodeReason
200 Zero or more assets successfully found
collins-shell asset find_similar 001367
curl --basic -u collins:collins 'http://localhost:9000/api/asset/001367/similar'
JSON Response 
{
  "status": "success:ok",
  "data": {
    "Pagination": {
      "PreviousPage": 0,
      "CurrentPage": 0,
      "NextPage": 1,
      "TotalResults": 435
    },
    "Data": [
      {
        "ID": 388,
        "TAG": "000915",
        "STATE": null,
        "STATUS": "Unallocated",
        "TYPE": "Server Node",
        "CREATED": "2012-04-05T23:40:42",
        "UPDATED": "2012-09-14T16:59:53",
        "DELETED": null
      },
      {
        "ID": 437,
        "TAG": "000919",
        "STATE": null,
        "STATUS": "Unallocated",
        "TYPE": "Server Node",
        "CREATED": "2012-04-05T23:42:33",
        "UPDATED": "2012-09-14T17:12:22",
        "DELETED": null
      },
      {
        "ID": 391,
        "TAG": "000923",
        "STATE": null,
        "STATUS": "Unallocated",
        "TYPE": "Server Node",
        "CREATED": "2012-04-05T23:41:03",
        "UPDATED": "2012-09-14T17:09:11",
        "DELETED": null
      }
    ]
  }
}

Asset Delete Tag
DescriptionDelete a tag associated with an asset
RequestDELETE /api/asset/:tag/attribute/:attribute
Permissioncontrollers.AssetApi.deleteAssetAttribute
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes) and unique
attribute String The attribute to be deleted, e.g. HOSTNAME
groupId Option[Integer] Used for deleting specific values from a multi-dimensional tag
Response Codes
CodeReason
202 Accepted for delete
404 Asset not found
collins-shell asset delete_attribute NODECLASS --tag=tumblrtag30
curl --basic -u collins:collins \
-X DELETE \
http://localhost:9000/api/asset/tumblrtag30/attribute/NODECLASS
JSON Response 
{
  "status": "success:accepted",
  "data": {
    "SUCCESS": true
  }
}

Asset Delete
DescriptionDecommission the specified asset
RequestDELETE /api/asset/:tag
Permissioncontrollers.AssetApi.deleteAsset
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes) and unique
reason String The reason the asset is being decommissioned
Response Codes
CodeReason
200 Asset has been decommissioned
404 Asset not found
409 Asset not in appropriate status (Cancelled, etc)
collins-shell asset delete --reason='Done with you' --tag=tumblrtag30
curl --basic -u collins:collins \
-X DELETE \
http://localhost:9000/api/asset/tumblrtag30
JSON Response 
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Asset Management API

Provisioning, power management, IPMI data

Overview

Most of the API endpoints that are part of the asset management API are provisioning, power, or IPMI related. All of the asset management endpoints are going to depend somewhat on how you have configured collins. While the API remains consistent, the under the hood behavior of Collins will depend greatly on configuration. For more details in provisioning, IPMI, and power configurations see the configuration documentation.

IPMI Management
DescriptionCreate or update IPMI data
RequestPOST /api/asset/:tag/ipmi
Permissioncontrollers.IpmiApi.updateIpmi
Note This is one of the few API endpoints that will both create and/or update a resource. This will likely change in the future (PUT for create, POST for update). If you are creating IPMI info, all parameters below are required. If you are updating IPMI info, at least one parameter must be specified.
Parameters
NameTypeDescription
username Option[String] The IPMI username - must be at least 1 character
password Option[String] The IPMI password - must be at least 8 characters
address Option[String] IPMI address - dotted quad (IPv4) and unused
gateway Option[String] IPMI gateway address - dotted quad (IPv4)
netmask Option[String] IPMI netmask - dotted quad (IPv4)
Response Codes
CodeReason
200 IPMI information successfully updated
201 IPMI information successfully created
404 Asset not found
409 Duplicate IPMI address
collins-shell ipmi create \
--address=172.168.0.33 \
--gateway=172.168.0.1 \
--netmask=255.255.255.0 \
--ipmi-username=root \
--ipmi-password=fizzbuzz \
--tag=tumblrtag2

collins-shell ipmi update --ipmi-password=fizzbuzz23 --tag=tumblrtag2
curl --basic -u collins:collins \
-d address=172.168.0.34 \
-d gateway=172.168.0.1 \
-d netmask=255.255.255.0 \
-d username=root \
-d password=fizzbuzz http://localhost:9000/api/asset/tumblrtag3/ipmi

curl --basic -u collins:collins \
-d password=fizzbuzz23 \
http://localhost:9000/api/asset/tumblrtag3/ipmi
JSON Response 
{
  "status": "success:created",
  "data": {
    "SUCCESS": true
  }
}
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Power Management
DescriptionSend a power management event to an asset.
RequestPOST /api/asset/:tag/power
Permissioncontrollers.AssetManagementApi.powerManagement
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
action String One of powerOff, powerOn, powerSoft, powerState, rebootHard, rebootSoft, identify, verify. Described below.
Power Actions
ActionDescription
powerOff Power off the asset, without grace (like pressing the power button)
powerOn Power up the asset
powerSoft Initiate soft shutdown of OS via ACPI
powerState Status of power (on, off, unknown)
rebootSoft Graceful reboot via IPMI, uses ACPI to notify OS
rebootHard This is equivalent to pressing the reset button
identify Turn on the IPMI light
verify Detect whether the IPMI interface is reachable
Response Codes
CodeReason
200 Successfully performed power operation
403 Forbidden by configuration
  • features.ignoreDangerousCommands - forbids managing power state
  • powermanagement.allowAssetTypes - forbids power managing this asset type
  • powermanagement.disallowStatus - forbids managing power state of asset with this status
  • powermanagement.disallowWhenAllocated - forbids using this power action when asset is Allocated
404 Asset not found
501 Plugin not enabled
collins-shell power rebootSoft --reason='Need to restart for maintenance' --tag=tumblrtag1
curl -v -u collins:collins --basic \
-d action=rebootSoft \
http://localhost:9000/api/asset/tumblrtag1/power
JSON Response 
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Power Status
DescriptionDetermine the power status for a machine (on, off, unknown)
RequestGET /api/asset/:tag/power
Permissioncontrollers.AssetManagementApi.powerStatus
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
Response Codes
CodeReason
200 Successfully retrieved power status
403 Forbidden by configuration
  • powermanagement.allowAssetTypes - forbids power managing this asset type
404 Asset not found
501 Plugin not enabled
collins-shell power_status --tag=tumblrtag1
curl -v -u collins:collins --basic http://localhost:9000/api/asset/tumblrtag1/power
JSON Response 
{
  "status": "success:ok",
  "data": {
    "MESSAGE": "on"
  }
}

Provision an Asset
DescriptionProvision the specified asset using the specified parameters.
RequestPOST /api/provision/:tag
Permissioncontrollers.AssetManagementApi.provisionAsset
Note This API call may take a long time (depending on the configured provisioning backend). Client implementations should account for this with an appropriate timeout.
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
profile String The provisioning profile to use. This is the PROFILE key from the get provisioning profiles response.
contact String The contact (username) for the provisioned host. This will be used later on for notification purposes.
suffix Option[String] If SUFFIX_ALLOWED is true for the specified profile, this may be supplied. This will be part of the hostname.
primary_role Option[String] If REQUIRES_PRIMARY_ROLE is true for the specified profile, and PRIMARY_ROLE is null, this value must be supplied.
secondary_role Option[String] If REQUIRES_SECONDARY_ROLE is true for the specified profile, and SECONDARY_ROLE is null, this value must be supplied.
pool String If REQUIRES_POOL is true for the specified profile, and POOL is null, this value must be supplied.
activate Option[Boolean] If the activation plugin is enabled and appropriate for the asset, this value must be true. This is primarily used in on-demand environments where you pull assets from a spare or on-demand pool.
Response Codes
CodeReason
200 Asset has successfully started the provisioning process
403 Forbidden by configuration
  • features.ignoreDangerousCommands - forbids managing power state
  • provisioner.allowedStatus - forbids asset with this status from being provisioned
404 Asset not found
429 You have exceeded the configured provisioning rate limit
501 Plugin not enabled
collins-shell provision host tumblrtag1 devnode collins --suffix=collins
curl -v -u collins:collins --basic \
-d profile=devnode \
-d contact=collins \
-d suffix=collins \
http://localhost:9000/api/provision/tumblrtag1
JSON Response 
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Get Provisioning Profiles
DescriptionRetrieve a list of available provisioning profiles.
RequestGET /api/provision/profiles
Permissioncontrollers.AssetManagementApi.getProvisioningProfiles
Parameters None
Response Codes
CodeReason
200 Successfully retrieved profiles
501 Plugin not enabled
collins-shell provision list
curl -u collins:collins --basic http://localhost:9000/api/provision/profiles
JSON Response 
{
    "status": "success:ok",
    "data": {
      "PROFILES": [
        {
          "PROFILE": "aaacanode",
          "LABEL": "AAA/CA Server",
          "PREFIX": "aaa",
          "SUFFIX_ALLOWED": true,
          "PRIMARY_ROLE": "INFRA",
          "REQUIRES_PRIMARY_ROLE": true,
          "POOL": null,
          "REQUIRES_POOL": true,
          "SECONDARY_ROLE": null,
          "REQUIRES_SECONDARY_ROLE": false
        },
        {
          "PROFILE": "adminwebnode",
          "LABEL": "Admin Web Server",
          "PREFIX": "adminweb",
          "SUFFIX_ALLOWED": false,
          "PRIMARY_ROLE": "TUMBLR_APP",
          "REQUIRES_PRIMARY_ROLE": true,
          "POOL": "ADMIN_POOL",
          "REQUIRES_POOL": true,
          "SECONDARY_ROLE": "ALL",
          "REQUIRES_SECONDARY_ROLE": false
        },
        {
          "PROFILE": "appcronnode",
          "LABEL": "App Cron Server",
          "PREFIX": "app-cron",
          "SUFFIX_ALLOWED": false,
          "PRIMARY_ROLE": "TUMBLR_APP",
          "REQUIRES_PRIMARY_ROLE": true,
          "POOL": "UTIL",
          "REQUIRES_POOL": true,
          "SECONDARY_ROLE": null,
          "REQUIRES_SECONDARY_ROLE": false
        },
        {
          "PROFILE": "assetnode",
          "LABEL": "Asset Server",
          "PREFIX": "assets",
          "SUFFIX_ALLOWED": false,
          "PRIMARY_ROLE": null,
          "REQUIRES_PRIMARY_ROLE": true,
          "POOL": null,
          "REQUIRES_POOL": true,
          "SECONDARY_ROLE": null,
          "REQUIRES_SECONDARY_ROLE": false
        }
      ]
    }
}

Asset Hierarchy API

Asset Hierarchy operations

Overview

The Asset Hierarchy API enables you to define physical hierarchical links betwen assets. This information is used to build Rack and Blade views. Please note this API is still experimental, and lacks complete tests and HTTP safety checks.

Asset Hierarchy Update
DescriptionCreate or update an Asset Hierarchy link
RequestPOST /api/hierarchy/:tag
Permissioncontrollers.HierarchyApi.updateHierarchy
Parameters
NameTypeDescription
tag String Tag for the parent Asset - Asset to add a child to
child String Tag for the child asset
start Option[Integer] Starting rack unit or blade slot for this asset
end Option[Integer] Ending rack unit or blade slot for this asset
Response Codes
CodeReason
201 Hierarchy succesfully updated
not yet implemented in collins shell
curl --basic -u collins:collins -X POST http://localhost:9000/api/asset/tumblrtag301 -d child_tag=tumblrtag400 -d start=3 -d end=5
JSON Response 
{
  "status": "success:created"
}

Asset Hierarchy Remove
DescriptionRemove Asset Hierarchy link
RequestDELETE /api/hierarchy/:tag/:child
Permissioncontrollers.HierarchyApi.updateHierarchy
Parameters
NameTypeDescription
tag String Tag for the parent Asset
child String Tag for the child asset
Response Codes
CodeReason
201 Hierarchy succesfully updated
not yet implemented in collins shell
curl --basic -u collins:collins -X DELETE http://localhost:9000/api/asset/tumblrtag301/tumblrtag400
JSON Response 
{
  "status": "success:created"
}

Asset Hierarchy Show Parent
DescriptionGet the parent of an asset
RequestGET /api/hierarchy/:tag/parent
Parameters
NameTypeDescription
tag String Tag for Asset to get the parent for
not yet implemented in collins shell
curl --basic -u collins:collins -X GET http://localhost:9000/api/hierarchy/tumblrtag301/parent

Asset Hierarchy Show Children
DescriptionGet the children of an asset
RequestGET /api/hierarchy/:tag/children.
Parameters
NameTypeDescription
tag String Tag for Asset to get the children of.
not yet implemented in collins shell
curl --basic -u collins:collins -X GET http://localhost:9000/api/hierarchy/tumblrtag301/children

Asset All Hierarchy Links
DescriptionGet all hierirchy links
RequestGET /api/hierarchy/nodes
not yet implemented in collins shell
curl --basic -u collins:collins -X GET http://localhost:9000/api/hierarchy/nodes

Asset Log API

Audit trail for your assets

Overview

The logs API is fairly straight forward, offering only 3 endpoints to interact with. You can create logs, fetch logs for a specific asset, or fetch all logs. All log levels (referred to as type in the API) are listed below.

LevelDescription
EMERGENCY A "panic" condition - notify all tech staff on call? (earthquake? tornado?) - affects multiple apps/servers/sites...
ALERT Should be corrected immediately - notify staff who can fix the problem - example is loss of backup ISP connection
CRITICAL Should be corrected immediately, but indicates failure in a primary system - fix CRITICAL problems before ALERT - example is loss of primary ISP connection
ERROR Non-urgent failures - these should be relayed to developers or admins; each item must be resolved within a given time
WARNING Warning messages - not an error, but indication that an error will occur if action is not taken, e.g. file system 85% full - each item must be resolved within a given time
NOTICE Events that are unusual but not error conditions - might be summarized in an email to developers or admins to spot potential problems - no immediate action required
INFORMATIONAL Normal operational messages - may be harvested for reporting, measuring throughput, etc - no action required
DEBUG Info useful to developers for debugging the application, not useful during operations
NOTE Creates by users via the web UI, can be any kind of message

Log Create
DescriptionCreate a new log entry for the specified asset
RequestPUT /api/asset/:tag/log
Permissioncontrollers.AssetLogApi.submitLogData
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
message String The message to log
type Option[String] The default is INFORMATIONAL
Note It is also possible to specify these parameters as the body of the PUT request with a Content-Type header of application/json. In this case, the body is a JSON encoded object with the keys Message (arbitrary JSON value) and Type (one of the strings specified above). This is useful for logging structured data.
Response Codes
CodeReason
201 Log entry was successfully created
404 Asset not found
collins-shell log 'Hello World' --severity=DEBUG --tag=tumblrtag1
curl --basic -u collins:collins -X PUT \
-d message='Hello World' \
-d type=DEBUG \
http://localhost:9000/api/asset/tumblrtag1/log
JSON Response 
{
  "status": "success:created",
  "data": {
    "SUCCESS": true
  }
}

Log Get
DescriptionGet logs associated with an asset
RequestGET /api/asset/:tag/logs
Permissioncontrollers.AssetLogApi.getLogData
Parameters Paginated
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
filter Option[String] A semicolon (;) list of log types to fetch. Prefix a type with a ! to exclude that type.
Response Codes
CodeReason
200 Zero or more logs were successfully retrieved
404 Asset not found
collins-shell logs tumblrtag1
curl --basic -u collins:collins http://localhost:9000/api/asset/tumblrtag1/logs
JSON Response 
{
  "status": "success:ok",
  "data": {
    "Pagination": {
      "PreviousPage": 0,
      "CurrentPage": 0,
      "NextPage": 0,
      "TotalResults": 3
    },
    "Data": [
      {
        "ID": 3,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T13:04:52",
        "FORMAT": "text\/plain",
        "SOURCE": "API",
        "TYPE": "DEBUG",
        "MESSAGE": "User collins: Hello World"
      },
      {
        "ID": 2,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T12:53:15",
        "FORMAT": "text\/plain",
        "SOURCE": "API",
        "TYPE": "DEBUG",
        "MESSAGE": "User collins: Hello World"
      },
      {
        "ID": 1,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T12:53:07",
        "FORMAT": "text\/plain",
        "SOURCE": "INTERNAL",
        "TYPE": "INFORMATIONAL",
        "MESSAGE": "Automatically created by database migration"
      }
    ]
  }
}

Log Get All
DescriptionGet all log data, not bound to a specific asset
RequestGET /api/assets/logs
Permissioncontrollers.AssetLogApi.getAllLogData
Parameters Paginated
NameTypeDescription
filter Option[String] A semicolon (;) list of log types to fetch. Prefix a type with a ! to exclude that type.
Response Codes
CodeReason
200 Zero or more logs were successfully retrieved
collins-shell logs all
curl --basic -u collins:collins http://localhost:9000/api/assets/logs
JSON Response 
{
  "status": "success:ok",
  "data": {
    "Pagination": {
      "PreviousPage": 0,
      "CurrentPage": 0,
      "NextPage": 0,
      "TotalResults": 3
    },
    "Data": [
      {
        "ID": 3,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T13:04:52",
        "FORMAT": "text\/plain",
        "SOURCE": "API",
        "TYPE": "DEBUG",
        "MESSAGE": "User collins: Hello World"
      },
      {
        "ID": 2,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T12:53:15",
        "FORMAT": "text\/plain",
        "SOURCE": "API",
        "TYPE": "DEBUG",
        "MESSAGE": "User collins: Hello World"
      },
      {
        "ID": 1,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T12:53:07",
        "FORMAT": "text\/plain",
        "SOURCE": "INTERNAL",
        "TYPE": "INFORMATIONAL",
        "MESSAGE": "Automatically created by database migration"
      }
    ]
  }
}

Tag API

System tag management

Overview

The tags API provides access to all system tags. It provides the ability to list all tags, and to list all values for a given tag. Note that it is not possible to list the values of encrypted tags.

List Tags
DescriptionList all tags that are in use
RequestGET /api/tags
Permissioncontrollers.TagApi.getTags
Parameters None
Response Codes
CodeReason
200 Zero or more tags successfully found
collins-shell tag list
curl --basic -u collins:collins http://localhost:9000/api/tags
JSON Response 
{
  "status": "success:ok",
  "data": {
    "tags": [
      {
        "name": "CHASSIS_TAG",
        "label": "Chassis Tag",
        "description": "Tag for asset chassis"
      },
      {
        "name": "CPU_CORES",
        "label": "CPU Cores",
        "description": "Number of cores per physical CPU"
      },
      {
        "name": "CPU_COUNT",
        "label": "CPU Count",
        "description": "Number of physical CPUs in asset"
      },
      {
        "name": "CPU_DESCRIPTION",
        "label": "CPU Description",
        "description": "CPU description, vendor labels"
      },
      {
        "name": "CPU_SPEED_GHZ",
        "label": "CPU Speed",
        "description": "CPU Speed in GHz"
      },
      {
        "name": "CPU_THREADS",
        "label": "CPU Threads",
        "description": "Number of threads per CPU core"
      },
      {
        "name": "DISK_DESCRIPTION",
        "label": "Disk Description",
        "description": "Vendor labels for disk"
      },
      {
        "name": "DISK_SIZE_BYTES",
        "label": "Disk Size",
        "description": "Disk size in bytes"
      },
      {
        "name": "DISK_STORAGE_TOTAL",
        "label": "Total disk storage",
        "description": "Total amount of available storage"
      },
      {
        "name": "DISK_TYPE",
        "label": "Inferred disk type",
        "description": "Inferred disk type: SCSI, IDE or FLASH"
      },
      {
        "name": "INTERFACE_ADDRESS",
        "label": "IP Address",
        "description": "Address on interface, e.g. 10.0.0.1"
      },
      {
        "name": "INTERFACE_NAME",
        "label": "Interface Name",
        "description": "Name of physical interface, e.g. eth0"
      },
      {
        "name": "LLDP_CHASSIS_DESCRIPTION",
        "label": "LLDP Chassis Description",
        "description": "Chassis Description reported by lldpctl"
      },
      {
        "name": "LLDP_CHASSIS_ID_TYPE",
        "label": "LLDP Chassis ID Type",
        "description": "Chassis ID Type reported by lldpctl"
      },
      {
        "name": "LLDP_CHASSIS_ID_VALUE",
        "label": "LLDP Chassis ID Value",
        "description": "Chassis ID Value reported by lldpctl"
      },
      {
        "name": "LLDP_CHASSIS_NAME",
        "label": "LLDP Chassis Name",
        "description": "Chassis name reported by lldpctl"
      },
      {
        "name": "LLDP_INTERFACE_NAME",
        "label": "LLDP Interface Name",
        "description": "Interface name reported by lldpctl"
      },
      {
        "name": "LLDP_PORT_DESCRIPTION",
        "label": "LLDP Port Description",
        "description": "Port Description reported by lldpctl"
      },
      {
        "name": "LLDP_PORT_ID_TYPE",
        "label": "LLDP Port ID Type",
        "description": "Port ID Type reported by lldpctl"
      },
      {
        "name": "LLDP_PORT_ID_VALUE",
        "label": "LLDP Port ID Value",
        "description": "Port ID Value reported by lldpctl"
      },
      {
        "name": "LLDP_VLAN_ID",
        "label": "LLDP VLAN ID",
        "description": "VLAN ID reported by lldpctl"
      },
      {
        "name": "LLDP_VLAN_NAME",
        "label": "LLDP VLANE Name",
        "description": "VLAN name reported by lldpctl"
      },
      {
        "name": "MAC_ADDRESS",
        "label": "MAC Address",
        "description": "MAC Address of NIC"
      },
      {
        "name": "MEMORY_BANKS_TOTAL",
        "label": "Memory Banks",
        "description": "Total number of memory banks"
      },
      {
        "name": "MEMORY_DESCRIPTION",
        "label": "Memory Description",
        "description": "Memory description, vendor label"
      },
      {
        "name": "MEMORY_SIZE_BYTES",
        "label": "Memory",
        "description": "Size of Memory Stick"
      },
      {
        "name": "MEMORY_SIZE_TOTAL",
        "label": "Memory Total",
        "description": "Total amount of available memory in bytes"
      },
      {
        "name": "NIC_DESCRIPTION",
        "label": "NIC Description",
        "description": "Vendor labels for NIC"
      },
      {
        "name": "NIC_SPEED",
        "label": "NIC Speed",
        "description": "Speed of nic, stored as bits per second"
      },
      {
        "name": "POWER_OUTLET",
        "label": "Power_outlet",
        "description": "POWER_OUTLET"
      },
      {
        "name": "POWER_PORT",
        "label": "Power Port",
        "description": "Power port of asset"
      },
      {
        "name": "RACK_POSITION",
        "label": "Rack Position",
        "description": "Position of asset in rack"
      },
      {
        "name": "SERVICE_TAG",
        "label": "Service Tag",
        "description": "Vendor supplied service tag"
      },
      {
        "name": "SWITCH_PORT",
        "label": "Switch Port",
        "description": "Switch port that asset is connected to"
      },
      {
        "name": "SYSTEM_PASSWORD",
        "label": "System_password",
        "description": "SYSTEM_PASSWORD"
      }
    ]
  }
}

List Tag Values
DescriptionList all the unique values given a specific tag
RequestGET /api/tag/:tag
Permissioncontrollers.TagApi.getTagValues
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes) and exist
Response Codes
CodeReason
200 One or more tag values successfully found
404 No such tag
collins-shell tag values CHASSIS_TAG
curl --basic -u collins:collins http://localhost:9000/api/tag/CHASSIS_TAG
JSON Response 
{
  "status": "success:ok",
  "data": {
    "values": [
      "chassis tag abc"
    ]
  }
}

IPAM API

IP Address Management

Overview

Collins provides a fairly robust IPAM system, complete with callbacks and hooks to drive automation for your networking devices. Address management comes in two forms, strict and non-strict. In strict mode, addresses can only by allocated or managed from predefined pools. The pool configuration is documented here. In non-strict mode, which is typically only suitable if you don't manage your own addresses, Collins will allow you to allocate any addresses, as long as they aren't in use.

In addition to address management (creates, deletes, etc), the Collins IPAM API allows you to easily query this information. You can find out which pools are in use as well as utilization statistics, you can find out which asset is using a particular address, you can find out which assets are in a particular pool.

Allocate an Address
DescriptionCreate one or more addresses in a pool
RequestPUT /api/asset/:tag/address
Permissioncontrollers.IpAddressApi.allocateAddress
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
count Option[Integer] Number of addresses to allocate. Must be between 1 and 10 if specified. Defaults to 1.
pool Option[String] The pool to allocate from. Values that are acceptable here depend on what address pool have been configured but common values would be none/empy (default pool), public (publicly routable IP address), backend (private addresses used for backend connectivity) or management (private addresses used for management connectivity)
Note By default no pools are configured. Your Collins administrator must tell you what pools are available for allocation or you can use the pools API endpoint.
Response Codes
CodeReason
201 Address created
404 Invalid asset specified
collins-shell ip_address allocate DEV --tag=tumblrtag1
curl --basic -u collins:collins -X PUT -d pool=DEV http://localhost:9000/api/asset/tumblrtag1/address
JSON Response 
{
  "status": "success:created",
  "data": {
    "ADDRESSES": [
      {
        "ASSET_ID": 1,
        "ASSET_TAG": "tumblrtag1",
        "GATEWAY": "172.16.5.1",
        "ADDRESS": "172.16.5.4",
        "NETMASK": "255.255.255.0",
        "POOL": "DEV",
        "ID": 1
      }
    ]
  }
}

Update an Address
DescriptionUpdate IP address information
RequestPOST /api/asset/:tag/address
Permissioncontrollers.IpAddressApi.updateAddress
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
old_address Option[String] Optional for creating an address and required for updating an address
address Option[String] Optional for update and required for create
gateway Option[String] Optional for update and required for create
netmask Option[String] Optional for update and required for create
pool Option[String] Optional for update and required for create
Note If all address information is supplied (address, gateway, and netmask), but no old_address is specified, Collins will attempt to create the address.
Response Codes
CodeReason
200 Address updated
201 Address created
404 Invalid asset specified
collins-shell ip_address update 172.16.5.4 --tag=tumblrtag1 --address=172.16.5.5
curl --basic -u collins:collins -X POST \
-d address=172.16.5.5 \
-d old_address=172.16.5.4 \
http://localhost:9000/api/asset/tumblrtag1/address
JSON Response 
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Delete an Address
DescriptionDelete all addresses associated with a given tag, optionally associated with a pool
RequestDELETE /api/asset/:tag/addresses
Permissioncontrollers.IpAddressApi.purgeAddresses
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
pool Option[String] If specified, only addresses associated with the given pool are deleted. Otherwise, all addresses are deleted.
Response Codes
CodeReason
200 Address deleted
404 Invalid asset specified
collins-shell ip_address delete DEV --tag=tumblrtag1
curl --basic -u collins:collins -X DELETE \
-d pool=DEV \
http://localhost:9000/api/asset/tumblrtag1/addresses
JSON Response 
{
  "status": "success:ok",
  "data": {
    "DELETED": 1
  }
}

Get Address Pools
DescriptionReturn pools that are in use or configured
RequestGET /api/address/pools
Permissioncontrollers.IpAddressApi.getAddressPools
Parameters
NameTypeDescription
all Option[Boolean] If false, only return pools with allocated assets. Defaults to true.
Response Codes
CodeReason
200 Pools found
collins-shell ip_address pools
curl --basic -u collins:collins http://localhost:9000/api/address/pools
JSON Response 
{
  "status": "success:ok",
  "data": {
    "POOLS": [
      {
        "NAME": "ADMIN-OPS",
        "NETWORK": "172.16.56.0\/24",
        "START_ADDRESS": "172.16.56.5",
        "SPECIFIED_GATEWAY": "Unspecified",
        "GATEWAY": "172.16.56.1",
        "BROADCAST": "172.16.56.255",
        "POSSIBLE_ADDRESSES": 254
      },
      {
        "NAME": "WEB-EDIT",
        "NETWORK": "172.16.64.0\/24",
        "START_ADDRESS": "172.16.64.5",
        "SPECIFIED_GATEWAY": "Unspecified",
        "GATEWAY": "172.16.64.1",
        "BROADCAST": "172.16.64.255",
        "POSSIBLE_ADDRESSES": 254
      },
      {
        "NAME": "DEV",
        "NETWORK": "172.16.5.0\/24",
        "START_ADDRESS": "172.16.5.4",
        "SPECIFIED_GATEWAY": "Unspecified",
        "GATEWAY": "172.16.5.1",
        "BROADCAST": "172.16.5.255",
        "POSSIBLE_ADDRESSES": 254
      },
      {
        "NAME": "WEB-SECURE",
        "NETWORK": "172.16.73.0\/28",
        "START_ADDRESS": "172.16.73.5",
        "SPECIFIED_GATEWAY": "Unspecified",
        "GATEWAY": "172.16.73.1",
        "BROADCAST": "172.16.73.15",
        "POSSIBLE_ADDRESSES": 14
      },
      {
        "NAME": "AAA",
        "NETWORK": "172.16.4.0\/28",
        "START_ADDRESS": "172.16.4.4",
        "SPECIFIED_GATEWAY": "Unspecified",
        "GATEWAY": "172.16.4.1",
        "BROADCAST": "172.16.4.15",
        "POSSIBLE_ADDRESSES": 14
      }
    ]
  }
}

Asset Addresses
DescriptionReturn addresses associated with an asset
RequestGET /api/asset/:tag/addresses
Permissioncontrollers.IpAddressApi.getForAsset
Parameters
NameTypeDescription
tag String Must be alphanumeric (but can include underscores and dashes)
Response Codes
CodeReason
200 Zero or more addresses found
collins-shell asset get tumblrtag1
curl --basic -u collins:collins http://localhost:9000/api/asset/tumblrtag1/addresses
JSON Response 
{
  "status": "success:ok",
  "data": {
    "ADDRESSES": [
      {
        "ASSET_ID": 1,
        "ASSET_TAG": "tumblrtag1",
        "GATEWAY": "172.16.5.1",
        "ADDRESS": "172.16.5.4",
        "NETMASK": "255.255.255.0",
        "POOL": "DEV",
        "ID": 2
      }
    ]
  }
}

Asset from Address
DescriptionGet the asset associated with a specific address
RequestGET /api/asset/with/address/:address
Permissioncontrollers.IpAddressApi.assetFromAddress
Parameters
NameTypeDescription
address String IPv4 address to find an asset for
Response Codes
CodeReason
200 Found an asset with the specified address
404 No asset found with the specified address
collins-shell ip_address find 172.16.5.4
curl --basic -u collins:collins http://localhost:9000/api/asset/with/address/172.16.5.4
JSON Response 
{
  "status": "success:ok",
  "data": {
    "ID": 1,
    "TAG": "tumblrtag1",
    "STATE": null,
    "STATUS": "Incomplete",
    "TYPE": "Server Node",
    "CREATED": "2012-09-17T14:07:19",
    "UPDATED": null,
    "DELETED": null
  }
}

Assets in a Pool
DescriptionGet the assets that are allocated in a specific pool
RequestGET /api/assets/with/addresses/in/:pool
Permissioncontrollers.IpAddressApi.assetsFromPool
Parameters
NameTypeDescription
pool String The pool to list assets for
Response Codes
CodeReason
200 Found one or more assets in the specified pool
404 No assets found in the specified pool, or the pool does not exist
collins-shell ip_address assets DEV
curl --basic -u collins:collins http://localhost:9000/api/assets/with/addresses/in/DEV
JSON Response 
{
  "status": "success:ok",
  "data": {
    "ASSETS": [
      {
        "ID": 1,
        "TAG": "tumblrtag1",
        "STATE": null,
        "STATUS": "Incomplete",
        "TYPE": "Server Node",
        "CREATED": "2012-09-17T14:07:19",
        "UPDATED": null,
        "DELETED": null
      }
    ]
  }
}

State API

Asset state management and API driven state machines

Overview

Collins provides comprehensive support for API driven asset state management. There is more information about states and state management in the concepts documentation.

State Create
DescriptionCreate a new asset state
RequestPUT /api/state/:name
Permissioncontrollers.AssetStateApi.createState
Parameters
NameTypeDescription
name String A unique name between 2 and 32 characters, must be upper case
label String A friendly display label between 2 and 32 characters
description String A longer description of the state between 2 and 255 characters
status Option[String] Name of the status to bind this state to (e.g. Incomplete, Maintenance, etc), or Any to bind to all status. Any is the default.
Response Codes
CodeReason
201 State was successfully created
409 State name already in use
collins-shell state create --name=HW_ON_FIRE \
--label='Hardware on Fire' \
--description='Use this state if hardware has caught on fire' \
--status=Maintenance
curl --basic -u collins:collins \
-X PUT \
-d label='Hardware on Fire' \
-d description='Use this state if hardware has caught on fire' \
-d status=Maintenance \
http://localhost:9000/api/state/HW_ON_FIRE
JSON Response 
{
  "status": "success:created",
  "data": {
    "SUCCESS": true
  }
}

State Update
DescriptionUpdate a state
RequestPOST /api/state/:old_name
Permissioncontrollers.AssetStateApi.updateState
Parameters
NameTypeDescription
old_name String The old name of the state
name Option[String] A new name, must be unique and between 2 and 32 characters
label Option[String] A friendly display label between 2 and 32 characters
description Option[String] A longer description of the state between 2 and 255 characters
status Option[String] Name of the status to bind this state to (e.g. Incomplete, Maintenance, etc), or Any to bind to all status.
Response Codes
CodeReason
200 State successfully updated
404 Invalid old_name specified
409 Name already in use or trying to modify a system name
collins-shell state update HW_ON_FIRE --label='Hardware on Fire!'
curl -v --basic -u collins:collins -d label='Hardware on Fire!' \
http://localhost:9000/api/state/HW_ON_FIRE
JSON Response 
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

State Delete
DescriptionDelete a state
RequestDELETE /api/state/:name
Permissioncontrollers.AssetStateApi.deleteState
Parameters
NameTypeDescription
name String Name of the state to delete
Response Codes
CodeReason
202 State accepted for deletion
404 Invalid name specified
409 Trying to modify a system name
collins-shell state delete HW_ON_FIRE
curl -v --basic -u collins:collins -X DELETE \
http://localhost:9000/api/state/HW_ON_FIRE
JSON Response 
{
  "status": "success:accepted",
  "data": {
    "DELETED": 2
  }
}

State Get
DescriptionGet a state by name
RequestGET /api/state/:name
Permissioncontrollers.AssetStateApi.getState
Parameters
NameTypeDescription
name String Name of the state to fetch
Response Codes
CodeReason
200 Found the named state
404 Invalid name specified
collins-shell state get HW_ON_FIRE
curl -v --basic -u collins:collins http://localhost:9000/api/state/HW_ON_FIRE
JSON Response 
{
  "status": "success:ok",
  "data": {
    "ID": 15,
    "STATUS": {
      "ID": 5,
      "NAME": "Maintenance",
      "DESCRIPTION": "Asset is scheduled for maintenance"
    },
    "NAME": "HW_ON_FIRE",
    "LABEL": "Hardware on Fire!",
    "DESCRIPTION": "Use this state if hardware has caught on fire"
  }
}

State Get All
DescriptionGet all available states
RequestGET /api/states
Permissioncontrollers.AssetStateApi.getState
Parameters None
Response Codes
CodeReason
200 Found some states
collins-shell state list
curl -v --basic -u collins:collins http://localhost:9000/api/states
JSON Response 
{
  "status": "success:ok",
  "data": [
    {
      "ID": 1,
      "STATUS": null,
      "NAME": "NEW",
      "LABEL": "New",
      "DESCRIPTION": "A service in this state is inactive. It does minimal work and consumes minimal resources."
    },
    {
      "ID": 2,
      "STATUS": null,
      "NAME": "STARTING",
      "LABEL": "Starting",
      "DESCRIPTION": "A service in this state is transitioning to Running."
    },
    {
      "ID": 3,
      "STATUS": null,
      "NAME": "RUNNING",
      "LABEL": "Running",
      "DESCRIPTION": "A service in this state is operational."
    },
    {
      "ID": 4,
      "STATUS": null,
      "NAME": "STOPPING",
      "LABEL": "Stopping",
      "DESCRIPTION": "A service in this state is transitioning to Terminated."
    },
    {
      "ID": 5,
      "STATUS": null,
      "NAME": "TERMINATED",
      "LABEL": "Terminated",
      "DESCRIPTION": "A service in this state has completed execution normally. It does minimal work and consumes minimal resources."
    },
    {
      "ID": 6,
      "STATUS": null,
      "NAME": "FAILED",
      "LABEL": "Failed",
      "DESCRIPTION": "A service in this state has encountered a problem and may not be operational. It cannot be started nor stopped."
    },
    {
      "ID": 7,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "RELOCATION",
      "LABEL": "Relocation",
      "DESCRIPTION": "An asset is being physically relocated."
    },
    {
      "ID": 8,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "IPMI_PROBLEM",
      "LABEL": "IPMI Problem",
      "DESCRIPTION": "An asset is experiencing IPMI issues and needs to be examined. It needs investigation."
    },
    {
      "ID": 9,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "HARDWARE_PROBLEM",
      "LABEL": "Hardware Problem",
      "DESCRIPTION": "An asset is experiencing a non-IPMI issue and needs to be examined. It needs investigation."
    },
    {
      "ID": 10,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "NETWORK_PROBLEM",
      "LABEL": "Network Problem",
      "DESCRIPTION": "An asset is experiencing a network problem that may or may not be hardware related. It needs investigation."
    },
    {
      "ID": 11,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "HARDWARE_UPGRADE",
      "LABEL": "Hardware Upgrade",
      "DESCRIPTION": "An asset is in need or in process of having hardware upgraded."
    },
    {
      "ID": 12,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "HW_TESTING",
      "LABEL": "Hardware Testing",
      "DESCRIPTION": "Performing some testing that requires putting the asset into a maintenance state."
    },
    {
      "ID": 13,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "MAINT_NOOP",
      "LABEL": "Maintenance NOOP",
      "DESCRIPTION": "Doing nothing, bouncing this through maintenance for my own selfish reasons."
    },
    {
      "ID": 15,
      "STATUS": {
        "ID": 5,
        "NAME": "Maintenance",
        "DESCRIPTION": "Asset is scheduled for maintenance"
      },
      "NAME": "HW_ON_FIRE",
      "LABEL": "Hardware on Fire",
      "DESCRIPTION": "Use this state if hardware has caught on fire"
    }
  ]
}

Misc. API

Miscellaneous endpoints that don't belong anywhere else

Overview

A collection of miscellaneous API methods that may be useful to you.

Timestamp
DescriptionFetch the current unix timestamp from this collins instance
RequestGET /api/timestamp
PermissionNone
Parameters None
Response Codes
CodeReason
200 Timestamp fetched
Note Output from this endpoint is only available as text
Not Implemented
curl http://localhost:9000/api/timestamp
Text Response 
1347919676

Ping
DescriptionCheck if collins is alive
RequestGET /api/ping
PermissionNone
Parameters None
Response Codes
CodeReason
200 Ping fetched
Note Output from this endpoint is only available as text
Not Implemented
curl http://localhost:9000/api/ping

Admin API

Collins Administrative operations

Overview

The Admin API contains endpoints for Collins administrative tasks.

Repopulate Solr
DescriptionTrigger repopulation of the Solr index. This does not normally need to be manually done, but useful for testing or after any database changes not done through Collins
RequestGET /api/admin/solr
Permissioncontrollers.Admin.clearCache
Parameters
NameTypeDescription
waitForCompletion Option[Boolean] True or false. If true, the request will block until the reindexing is complete. Otherwise the request will return immediately and reindexing will occur asynchronously.
Response Codes
CodeReason
200 Reindexing complete (if waitForCompletion) or reindexing started
Not Implemented
curl --basic -u collins:collins http://localhost:9000/api/admin/solr