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
DICE Web>ManagedPlatformUnit>TartarusManual>TartarusRESTAPI (24 Sep 2019, AlastairScobie)EditAttach
EXT 
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.