Tartarus API (prototype)
The Tartarus API can be used for querying and updating information on a item (desktop PC, server, laptop, external disk, GPU card etc).
URLs
The Tartarus API is available at -
https://tartarus.inf.ed.ac.uk/cgi-bin/gssapi-rest/rest/
Types (as used in following tables)
boolean |
one of 0 n N f F 1 y Y T t |
iid |
item id |
vmid |
vm id |
po |
purchase order id |
like_string |
wildcard as used by SQL LIKE operator (remember to encode any % characters) |
date |
date of form YYYY-MM-DD, but also accepts 'today' and 'yesterday' |
allocated-type |
one of - person, server, podium, lab, public, unallocated, junk, other |
managed-type |
one of - unknown, mdp, dice, selfdynamic, selfstatic, managed, other |
disposal-type |
one of - stolen, lost, contract, sold, transferred, destroyed, donated, other |
Unique returns
GET /items/iid |
Returns full information (including macaddrs) on item iid. Note that the returned 'cost' is inclusive of VAT |
eg GET /items/5465 |
GET /items/iid?with_children=boolean |
As above but includes a list of URLs pointing to items (eg GPU cards) associated with this item |
GET /items/iid/logbook |
Returns the logbook entries for item iid. |
GET /macaddrs/xx:xx:xx:xx:xx:xx |
Returns macaddr_id, generate_dhcp flag, associated item (url) |
GET /orders/po |
Returns information on purchase order po. Response will include links to items on order (of form http://tartarus.../rest/items/iid). |
GET /reports?hostname=hostname |
Returns client report information for the specified hostname. |
Search
GET /items?q1=x&q2=y |
Returns a list of URLs of form http://tartarus.../rest/items/iid |
serial=like-string |
eg GET /items?serial=7FU% |
|
description=like-string |
|
purchase_order=like-string |
eg GET /items?purchase_order=INF9376 |
requestor=like-string |
|
barcode=like-string |
|
hostname=like-string |
eg GET /items?hostname=gala%.inf.ed.ac.uk |
|
is_a_system=boolean |
managed_type=managed-type |
|
manager=like_string |
parent=iid |
|
allocated_to=like-string |
UUN |
allocated_type=allocated_type |
|
owner=like_string |
|
location=like_string |
|
manual_location=like_string |
sub_location=like_string |
disposal_date=date |
disposal_type=disposal_type |
disposed=boolean |
category=like_string |
Should this be a like_string? |
orphaned=boolean |
with_serial=boolean |
with_description=boolean |
with_hostname=boolean |
with_allocated_to=boolean |
Not yet implemented |
|
GET /orders?q1=x&q2=y |
Returns a list of URLs of form http://tartarus.../rest/orders/{po} |
supplier=like_string |
|
order_date=date |
|
ticket=like_string |
|
contract=like_string |
Inserts
POST /vms?guest_name=hostname&vmhost_id=iid[&macaddr=macaddr] |
Register a VM called hostname hosted on the server with item id iid, optionally registering macaddr |
POST /items/iid/logbook?comment=string |
Creates a log book entry for item iid |
POST /items/iid?macaddr=xx:xx:xx:xx:xx:xx |
Associates the specified address with item iid |
|
Updates
|
PUT /items/iid?s1=x&s2=y |
updates relevant fields of item iid |
hostname=string |
|
barcode=string |
allocated_to=UUN |
allocated_type=allocated_type |
owner=string |
manager=string |
managed_type=managed_type |
manual_location=string |
sub_location=string |
parent=iid |
(omit iid if you want to disassociate this item from its parent) |
last_confirmed_date=date |
disposal_date=date |
|
disposal_type=disposal_type |
disposal_extra=string |
|
PUT /macaddrs/xx:xx:xx:xx:xx:xx?generate_dhcp=boolean |
Sets the generate DHCP flag for the specified mac addr |
|
PUT /vms/vmid?vmhost_iid=iid |
Moves the VM vmid to a new host server iid |
Can also be used to indicate 'still here' (updating last_seen field) |
Deletes
DELETE /macaddrs/xx:xx:xx:xx:xx:xx |
Deletes the specified macaddr |
DELETE /vms/vmid |
Delete the VM with vmid vmid |
Examples
Return a list of items which have hostnames matching gala%.inf.ed.ac.uk
curl --negotiate --user dummy:dummy -X GET -H 'Content-Type: text/x-json'
https://tartarus.inf.ed.ac.uk/cgi-bin/gssapi-rest/rest/items?hostname='gala%.inf.ed.ac.uk'
will return
[{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/gssapi-rest/rest/items/30117","item_id":30117},{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/gssapi-rest/rest/items/31031","item_id":31031},{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/gssapi-rest/rest/items/31035","item_id":31035}]
Return information on item with item-id = 31031
curl --negotiate --user dummy:dummy -X GET -H 'Content-Type: text/x-json'
https://tartarus.inf.ed.ac.uk/cgi-bin/gssapi-rest/rest/items/31031
will return
{"allocated_type":"person","is_a_system":1,"model":null,"hostname":"gala.inf.ed.ac.uk","macaddrs":[{"macaddr":"b4:b5:2f:c2:08:52","generate_dhcp":0}],"vm_host":null,"item_id":31031,"os":null,"managed_type":"unknown","disposal_extra":null,"last_seen":null,"category":"desktop","purchase_order":"UOE54404","cost":"397.06","parent":null,"location":"AT-7.09A","serial":"CZC2457YM0","barcode":null,"serial_alt":null,"description":"HP 8300CMT i5 3.2GHz, 8GB, 500GB","delivered_date":"2012-11-19","sub_location":null,"requestor":"ascobie","warranty":"3yr","last_confirmed_date":null,"budget":"747DIV/G40588","kernel":null,"disposed":0,"orphaned":0,"last_reported":null,"disposal_date":null,"owner":"informatics","make":null,"purchase":{"last_loaded":1501241665,"contract":"SelectPC","vat":"1.2","order_date":"2012-11-07","supplier":"HP","ticket":"UNKNOWN","purchase_order":"UOE54404"},"manual_location":null,"allocated_to":{"uun":"ascobie","category":"Computing","last_name":"Scobie","first_name":"Alastair"},"manager":"ascobie","guests":[],"aliases":[],"disposal_type":null}
Mark item 31031 as being allocated to 'ascobie'
curl --negotiate --user dummy:dummy -X PUT -H 'Content-Type: text/x-json'
https://tartarus.inf.ed.ac.uk/cgi-bin/gssapi-rest/rest/items/31031?allocated_to=ascobie
will return
{"status":"updated"}
Sample Perl script to query information by hostname
- lwpquery: A sample perl script to query the REST api
Known bugs/issues
--
AlastairScobie - 23 May 2016