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

Topic attachments
I Attachment Action Size Date Who Comment
elseEXT lwpquery manage 1.6 K 30 Apr 2019 - 14:21 AlastairScobie A sample perl script to query the REST api
Topic revision: r45 - 24 Sep 2019 - 13:50:23 - AlastairScobie
DICE.TartarusRESTAPI moved from DICE.InvProjectRESTapi on 24 Sep 2019 - 13:50 by AlastairScobie - put it back
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies