Collins API

Getting RESTful with your assets

Overview

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

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 by 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
ipmi_pool Option[String] If provided, this overrides the default IPMI pool to allocate OOB IP from. This only takes effect if `generate_ipmi=true`. Default is empty, which uses whatever the currently configured IPMI address pool is.
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
400 IPMI pool provided does not exist
409 Asset with specified tag already exists 
collins-shell asset create --tag=TAG [--ipmi=(true|false) --status=STATUS --type=TYPE]
curl --basic -u blake:admin:first -X PUT http://localhost:9000/api/asset/tumblrtag30
c.create!('test01', generate_ipmi: true)  # default IPMI pool
c.create!('test02', generate_ipmi: true, ipmi_pool: 'OOB-POD03')
c.create!('config_vip', type: :configuration, generate_ipmi: false, status: :allocated)

json response example 

{
  "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 example 

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 example 

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
NoteIf you are setting an encrypted tag, you must also have the feature.canWriteEncryptedTags permission. See the features documentation for more information.
Parameters
NameTypeDescription
lshw Option[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 Option[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 blake:admin:first \
  --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

json response example 

{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

bash response example 

SUCCESS=true;

text response example 

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 blake:admin:first \
  -d status=Unallocated \
  -d state=Running \
  -d reason='Ready for action' \
  http://localhost:9000/api/asset/tumblrtag30/status

json response example 

{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Asset get
DescriptionGet an asset by tag
RequestGET /api/asset/:tag
Permissioncontrollers.AssetApi.getAsset
NoteIf the asset has encrypted tags, they will be hidden unless you have the feature.canSeeEncryptedTags permission. See the features documentation for more information.
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 blake:admin:first http://localhost:9000/api/asset/tumblrtag30

json response example 

{
   "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": ""
          }
        ]
      },
      "CLASSIFICATION": {
        "ID": 3,
        "TAG": "dell_r610",
        "STATE": null,
        "STATUS": "Incomplete",
        "TYPE": "CONFIGURATION",
        "CREATED": "2017-04-21T14:47:37",
        "UPDATED": "2017-04-21T14:48:08",
        "DELETED": null
      },
      "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 blake:admin:first 'http://localhost:9000/api/assets?attribute=NODECLASS%3Bweb&status=Unallocated'

json response example 

{
  "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
NoteThis 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
onlyUnallocated Option[Boolean] If true, return only assets that are in unallocated state. Defaults to true.
Response Codes
CodeReason
200 Zero or more assets successfully found 
collins-shell asset find_similar 001367
curl --basic -u blake:admin:first 'http://localhost:9000/api/asset/001367/similar'

json response example 

{
  "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 blake:admin:first -X DELETE http://localhost:9000/api/asset/tumblrtag30/attribute/NODECLASS

json response example 

{
  "status": "success:accepted",
  "data": {
    "SUCCESS": true
  }
}

Asset delete
DescriptionPermanently delete 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
nuke Boolean Must be a boolean value, set to true to permanently delete the asset
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 --nuke=true
curl --basic -u blake:admin:first -d nuke=true -X DELETE http://localhost:9000/api/asset/tumblrtag30

json response example 

{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Decommission asset
DescriptionDecommission the specified asset
RequestPOST /api/asset/:tag
Permissioncontrollers.AssetApi.updateAssetStatus
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 set_status --status='Decommissioned' --reason='Done with you' --tag=tumblrtag30
curl --basic -u blake:admin:first -d status="Decommissioned" -X POST http://localhost:9000/api/asset/tumblrtag30

json response example 

{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Asset type

Overview

The Asset Type API allows you to create and manage new types of assets, aside from the built in asset types (i.e. SERVER_NODE, CONFIGURATION, SWITCH). This provides a CRUD interface to defining new asset types for your own use.

Asset type create
DescriptionCreate a new asset type
RequestPUT /api/assettype/:name
Permissioncontrollers.AssetTypeApi.createAssetType
Parameters
NameTypeDescription
name String Must be alphanumeric (but can include underscores and dashes) and unique
label String Human readable label for the asset type. 2-32 characters.
Response Codes
CodeReason
201 Asset type was successfully created
409 Asset type with specified name already exists 
collins-shell asset_type create --name=NAME --label=LABEL
curl -XPUT -u blake:admin:first --basic \ -d label='Service Asset Type' \ http://localhost:9000/api/assettype/SERVICE

json response example 

{"status"=>"success:created", "data"=>{"SUCCESS"=>true}}

bash response example 

SUCCESS=true;

text response example 

SUCCESS true

Asset type update
DescriptionUpdate an asset type
RequestPOST /api/assettype/:tag
Permissioncontrollers.AssetTypeApi.updateAssetType
Parameters
NameTypeDescription
name String New name of the asset type (i.e. SERVICE). All uppercase, 2-32 chars.
label String New label of the asset type. 2-32 chars.
Response Codes
CodeReason
200 Asset type updated successfully
404 The specified asset type was not found 
collins-shell asset_type update OLDNAME [--name=NAME --label=LABEL]
curl -v -u blake:admin:first --basic -d name='NEW_NAME' http://localhost:9000/api/assettype/OLD_NAME

json response example 

{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

bash response example 

SUCCESS=true;

text response example 

SUCCESS=true;

Asset type get
DescriptionGet an asset type by name
RequestGET /api/assettype/:name
Permissioncontrollers.AssetTypeApi.getAssetType
Parameters
NameTypeDescription
name String Must be alphanumeric (but can include underscores and dashes) and unique
Response Codes
CodeReason
200 Asset type was found
404 Asset type could not be found 
collins-shell asset_type get NAME
curl --basic -u blake:admin:first http://localhost:9000/api/assettype/tumblrtag30

json response example 

{
  "status":"success:ok",
  "data":{
    "ID":1,
    "NAME":"SERVER_NODE",
    "LABEL":"Server Node"
  }
}

Asset type list
DescriptionGet all asset types
RequestGET /api/assettypes
Permissioncontrollers.AssetTypeApi.getAssetType
Response Codes
CodeReason
200 Success
404 Asset types could not be found 
collins-shell asset_type list
curl --basic -u blake:admin:first http://localhost:9000/api/assettypes

json response example 

{
  "status":"success:ok",
  "data":[
    { "ID":1,
      "NAME":"SERVER_NODE",
      "LABEL":"Server Node"
    },
    { "ID":2,
      "NAME":"SERVER_CHASSIS",
      "LABEL":"Server Chassis"
    },
    { "ID":3,
      "NAME":"RACK",
      "LABEL":"Rack"
    },
    { "ID":4,
      "NAME":"SWITCH",
      "LABEL":"Switch"
    },
    { "ID":5,
      "NAME":"ROUTER",
      "LABEL":"Router"
    },
    { "ID":6,
      "NAME":"POWER_CIRCUIT",
      "LABEL":"Power Circuit"
    },
    { "ID":7,
      "NAME":"POWER_STRIP",
      "LABEL":"Power Strip"
    },
    { "ID":8,
      "NAME":"DATA_CENTER",
      "LABEL":"Data Center"
    },
    { "ID":9,
      "NAME":"CONFIGURATION",
      "LABEL":"Configuration"
    }
  ]
}

Asset type delete
DescriptionDelete the specified asset type
RequestDELETE /api/assettype/:name
Permissioncontrollers.AssetTypeApi.deleteAssetType
Parameters
NameTypeDescription
name String Must be alphanumeric (but can include underscores and dashes) and unique
Response Codes
CodeReason
200 Asset type has been deleted
404 Asset type not found
409 System asset types cannot be deleted
500 Asset type unable to be deleted (Assets of this type still exist?) 
collins-shell asset_type delete NAME
curl --basic -u blake:admin:first -X DELETE http://localhost:9000/api/assettype/NAME

json response example 

{
  "status": "success:ok",
  "data": {
    "DELETED": 1
  }
}

Asset managment

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 configuration generate
DescriptionGenerate IPMI configuration on an asset without IPMI details
RequestPUT /api/asset/:tag/ipmi
Permissioncontrollers.IpmiApi.generateIpmi
NotePool is an optional parameter. If not specified, this behaves identically to how the asset create endpoint works when generate_ipmi is enabled.
Parameters
NameTypeDescription
pool Option[String] The IPMI pool to allocate address from
Response Codes
CodeReason
201 IPMI information successfully created
400 IPMI pool provided does not exist 
collins-shell ipmi generate --pool=OOB-POD02 --tag=tumblrtag2

collins.ipmi_allocate('tumblrtag2', pool: 'OOB-POD02')
curl --basic -u blake:admin:first http://localhost:9000/api/asset/tumblrtag3/ipmi
curl --basic -u blake:admin:first -d pool=OOB-POD02 http://localhost:9000/api/asset/tumblrtag2/ipmi

Ipmi configuration update
DescriptionUpdate IPMI configuration on an asset
RequestPOST /api/asset/:tag/ipmi
Permissioncontrollers.IpmiApi.updateIpmi
NoteThis 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 between 4 and 20 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 blake:admin:first \
-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 blake:admin:first \
-d password=fizzbuzz23 \
http://localhost:9000/api/asset/tumblrtag3/ipmi

json response example 

{
  "status": "success:created",
  "data": {
    "SUCCESS": true
  }
}
{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Power managment
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.
Action Description
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 blake:admin:first --basic -d action=rebootSoft http://localhost:9000/api/asset/tumblrtag1/power

json response example 

{
  "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 blake:admin:first --basic http://localhost:9000/api/asset/tumblrtag1/power

json response example 

{
  "status": "success:ok",
  "data": {
    "MESSAGE": "on"
  }
}

Provisioning profiles
DescriptionGet the available profiles for provisioning
RequestGET /api/provision/profiles
Permissioncontrollers.AssetManagementApi.getProvisioningProfiles
Response Codes
CodeReason
200 Profiles retreived and returned successfully
501 Plugin not enabled 
collins-shell provision list
curl -v -u blake:admin:first --basic http://localhost:9000/api/provision/profiles

json response example 

{
  "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
      }
    ]
  }
}

Provision an asset
DescriptionProvision the specified asset using the specified parameters.
RequestPOST /api/provision/:tag
Permissioncontrollers.AssetManagementApi.provisionAsset
NoteThis 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 blake --suffix=blake
curl -v -u blake:admin:first --basic \
-d profile=devnode \
-d contact=blake \
-d suffix=blake \
http://localhost:9000/api/provision/tumblrtag1

json response example 

{
  "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 log

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
NoteIt 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.
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
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 blake:admin:first -X PUT -d message='Hello World' -d type=DEBUG http://localhost:9000/api/asset/tumblrtag1/log

json response example 

{
  "status": "success:created",
  "data": {
    "SUCCESS": true,
    "Data": {
      "ID": 2,
      "ASSET_TAG": "tumblrtag1",
      "CREATED": "2016-09-16T16:48:40",
      "CREATED_BY": "blake",
      "FORMAT": "text/plain",
      "SOURCE": "API",
      "TYPE": "DEBUG",
      "MESSAGE": "Hello World"
    }
  }
}

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 blake:admin:first http://localhost:9000/api/asset/tumblrtag1/logs

json response example 

{
  "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",
        "CREATED_BY": "blake",
        "FORMAT": "text\/plain",
        "SOURCE": "API",
        "TYPE": "DEBUG",
        "MESSAGE": "User blake: Hello World"
      },
      {
        "ID": 2,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T12:53:15",
        "CREATED_BY": "blake",
        "FORMAT": "text\/plain",
        "SOURCE": "API",
        "TYPE": "DEBUG",
        "MESSAGE": "User blake: Hello World"
      },
      {
        "ID": 1,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T12:53:07",
        "CREATED_BY": "blake",
        "FORMAT": "text\/plain",
        "SOURCE": "INTERNAL",
        "TYPE": "INFORMATIONAL",
        "MESSAGE": "Automatically created by database migration"
      }
    ]
  }
}

Log get id
DescriptionGet a log by its ID number
RequestGET /api/log/:id
Permission
Parameters
NameTypeDescription
id Integer The unique log ID to retrieve
Response Codes
CodeReason
200 Log successfully retrieved
404 Log could not be found 
curl --basic -u blake:admin:first http://localhost:9000/api/log/42

json response example 

{
  "status": "success:ok",
  "data": {
    "Pagination": {
    "PreviousPage": 0,
    "CurrentPage": 0,
    "NextPage": 1,
    "TotalResults": 1
  },
  "Data": [
    {
      "ID": 42,
      "ASSET_TAG": "sl-102313",
      "CREATED": "2012-02-08T04:05:06",
      "FORMAT": "text/plain",
      "SOURCE": "API",
      "TYPE": "DEBUG",
      "MESSAGE": "hello world log"
    }
  ]}
}

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 blake:admin:first http://localhost:9000/api/assets/logs

json response example 

{
  "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 blake: Hello World"
      },
      {
        "ID": 2,
        "ASSET_TAG": "tumblrtag1",
        "CREATED": "2012-09-17T12:53:15",
        "FORMAT": "text\/plain",
        "SOURCE": "API",
        "TYPE": "DEBUG",
        "MESSAGE": "User blake: 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

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
Response Codes
CodeReason
200 Zero or more tags successfully found 
collins-shell tag list
curl --basic -u blake:admin:first http://localhost:9000/api/tags

json response example 

{
  "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 blake:admin:first http://localhost:9000/api/tag/CHASSIS_TAG

json response example 

{
  "status": "success:ok",
  "data": {
    "values": [
      "chassis",
      "tag",
      "abc"
    ]
  }
}

Ipam

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
NoteBy 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.
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)
Response Codes
CodeReason
201 Address created
404 Invalid asset specified 
collins-shell ip_address allocate DEV --tag=tumblrtag1
curl --basic -u blake:admin:first -X PUT -d pool=DEV http://localhost:9000/api/asset/tumblrtag1/address

json response example 

{
  "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
NoteIf all address information is supplied (address, gateway, and netmask), but no old_address is specified, Collins will attempt to create the address.
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
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 blake:admin:first -X POST \
-d address=172.16.5.5 \
-d old_address=172.16.5.4 \
http://localhost:9000/api/asset/tumblrtag1/address

json response example 

{
  "status": "success:ok",
  "data": {
    "SUCCESS": true
  }
}

Delete an address
DescriptionDelete addresses associated with a given tag: either all addresses, those associated with a specified pool, or a single address. If this endpoint is called with no parameters all addresses will be deleted. Both pool and address can't be set in a single request.
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.
address Option[String] If specified, delete only the given address. 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 blake:admin:first -X DELETE \
-d pool=DEV \
http://localhost:9000/api/asset/tumblrtag1/addresses

json response example 

{
  "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 blake:admin:first http://localhost:9000/api/address/pools

json response example 

{
  "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
      }
    ]
  }
}

Get ipmi address pools
DescriptionReturn ipmi pools that are configured
RequestGET /api/ipmi/pools
Permissioncontrollers.IpmiApi.GetAddressPools
NoteIf no IPMI pools are configured the parent level ipmi block settings are returned with a pool name of default. In the case of the parent level IPMI block being set as well pools defined only the pools will be returned due to some legacy code around ipmi pool loading.
Response Codes
CodeReason
200 Pools found 
collins-shell ipmi pools
curl --basic -u blake:admin:first http://localhost:9000/api/ipmi/pools

json response example 

{
  "status": "success:ok",
  "data": {
    "POOLS": [
      {
        "NAME": "OOB-POD01",
        "NETWORK": "172.16.32.0/20",
        "START_ADDRESS": "172.16.32.20",
        "SPECIFIED_GATEWAY": "Unspecified",
        "GATEWAY": "172.16.32.1",
        "BROADCAST": "172.16.47.255",
        "POSSIBLE_ADDRESSES": 4094
      }
    ]
  }
}

Asset addresses
DescriptionReturn addresses associated with an asset
RequestGET /api/asset/:tag/addresses
Permissioncontrollers.IpAddressApi.getForAsset
Parameters
NameTypeDescription
tag String
Response Codes
CodeReason
200 Zero or more addresses found 
collins-shell asset get tumblrtag1
curl --basic -u blake:admin:first http://localhost:9000/api/asset/tumblrtag1/addresses

json response example 

{
  "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

State

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 blake:admin:first \
  -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 example 

{
  "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 blake:admin:first -d label='Hardware on Fire!' http://localhost:9000/api/state/HW_ON_FIRE

json response example 

{
  "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 blake:admin:first -X DELETE http://localhost:9000/api/state/HW_ON_FIRE

json response example 

{
  "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 blake:admin:first http://localhost:9000/api/state/HW_ON_FIRE

json response example 

{
  "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
Response Codes
CodeReason
200 Found some states 
collins-shell state list
curl -v --basic -u blake:admin:first http://localhost:9000/api/states

json response example 

{
  "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"
    }
  ]
}

Firehose

Overview

Collins provides a simple firehose that clients can use to get near real-time notifications about updates to assets. Updates are pushed using server-sent events, and contains information about the type of update, which asset was updated and information about the asset in JSON format.

Consume firehose
DescriptionOpen a connection to receive server-sent events about asset updates
RequestGET /api/firehose
Permissioncontrollers.Firehose.stream
NoteOutput from this endpoint is only available as content type text/event-stream in SSE format
Response Codes
CodeReason
200 Connection successful 
curl --basic -u blake:admin:first http://localhost:9000/api/firehose

SSE response example 

event: asset_update
data: {"name":"asset_update","tag":"tumblrtag30","category":"Asset","data":{"ASSET":{"ID":1,"TAG":"tumblrtag30","STATE":{"ID":3,"STATUS":null,"NAME":"RUNNING","LABEL":"Running","DESCRIPTION":"A service in this state is operational."},"STATUS":"Allocated","TYPE":"SERVER_NODE","CREATED":"2013-08-28T12:51:00","UPDATED":"2015-12-05T19:53:27","DELETED":null}}}

event: asset_create
data: {"name":"asset_create","tag":"tumblrtag31","category":"Asset","data":{"ASSET":{"ID":2,"TAG":"tumblrtag31","STATE":null,"STATUS":"Incomplete","TYPE":"SERVER_NODE","CREATED":"2016-01-13T11:30:37","UPDATED":null,"DELETED":null}}}

event: asset_delete
data: {"name":"asset_delete","tag":"tumblrtag32","category":"Asset","data":{"ASSET":{"ID":3,"TAG":"tumblrtag32","STATE":{"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."},"STATUS":"Decommissioned","TYPE":"SERVER_NODE","CREATED":"2016-01-13T11:38:25","UPDATED":"2016-01-13T11:38:50","DELETED":"2016-01-13T11:39:06"}}}

event: ipAddresses_create
data: {"name":"ipAddresses_create","tag":"tumblrtag30","category":"IpAddress","data":{"ASSET":{"ID":1,"TAG":"tumblrtag30","STATE":null,"STATUS":"Incomplete","TYPE":"SERVER_NODE","CREATED":"2016-01-13T11:41:26","UPDATED":null,"DELETED":null},"ADDRESSES":[{"ASSET_ID":1,"ASSET_TAG":"tumblrtag30","GATEWAY":"172.16.5.1","ADDRESS":"172.16.5.4","NETMASK":"255.255.255.0","POOL":"DEV","ID":1}]}}

Admin

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 
curl --basic -u blake:admin:first http://localhost:9000/api/admin/solr

text response example 

OK

Misc

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
NoteOutput from this endpoint is only available as text
Response Codes
CodeReason
200 Timestamp fetched 
curl http://localhost:9000/api/timestamp

text response example 

1347919676

Ping
DescriptionCheck if collins is alive
RequestGET /api/ping
PermissionNone
NoteOutput from this endpoint is only available as text
Response Codes
CodeReason
 
curl http://localhost:9000/api/ping

text response example 

pong