4.2 Working with hosts

Verb

address

notes

additional details

GET

/hosts

/hosts?page=X

&page_size=Y

Retrieves a paginated list of all hosts, Y at a time (by default 25). Each array entry includes details about the host.

The beginning of each response includes a count and a link to the next page. Each entry in the list has a link to itself.

GET

/hosts/<id>

Retrieves an individual host. If an invalid host id is given, a “Not found” error is returned.

POST

/hosts

Creates a new host. Only the sheets field is required, which must be specified by ID. You must be a sheet owner to add a host to any specific sheet. The new host is returned.

If a location is specified, the individual components of the location object are verified to try to find a matching location ID. If an exact match cannot be found, then an error is returned and the host will not be added.

The format of the location field is {

  “site”: string,

  “building”: string,

  “floor”: string,

  “room”: string

}

body {

  “names”: array of strings,

  “sheets”: array of strings (sheet IDs),

  “description”: string,

  “ips”: string,

  “macs”: string,

  “aco”: string,

  “location”: {location object},¹

  “off_premises”: Boolean (true/false)²

  “classification”: string (implementation-dependent code),

  “categories”: array of strings (implementation-dependent codes),

  “priority”: string (code),

  “system_type”: string (code),

  “free_fields”: json,

  “owners”: array of strings³,

  “it_contacts”: array of strings³,

  “users”: array of strings³

}

¹The location field is handled in a special way, detailed at left.

²If true, location notes must be included.

³You can specify usernames, email addresses, groups and/or organizational unit code.

PUT

/hosts/<id>

Updates (replaces) an existing host. Returns the updated host object.

Include the sheets field, along with any other fields you want to change.

DELETE

/hosts/<id>

Removes the host. No content is returned.

GET

/hosts?sheet=<id>

&page_size=Y

Retrieves a paginated list of hosts belonging to the sheet in arrays of up to Y (by default 25) at a time. Each entry includes some details about the host.

The beginning of each response includes a count and a link to the previous and next pages Each entry in the array has a link to itself.

GET

/hosts?search=string

&page_size=Y

Returns host objects matching the search string.

Useful for testing. Only host objects are searched.