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

There are two URLs. Both are HTTPS only. Note that these URLs are very likely to change during development.

Unauthenticated access (query only) https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/
GSSAPI authenticated access (query and/or update) https://tartarus.inf.ed.ac.uk/cgi-bin/rest/rest/

Types (as used in following tables)

boolean one of 0 n N f F 1 y Y T t
iid item 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.
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.../api/items/iid).

Search

GET /items?q1=x&q2=y Returns a list of URLs of form http://tartarus.../api/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.../api/orders/{po}
supplier=like_string  
order_date=date  
ticket=like_string  
contract=like_string

Updates

POST /items/iid/logbook?comment=string Creates a log book entry for item iid
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
POST /items/iid?macaddr=xx:xx:xx:xx:xx:xx Associates the specified address with item iid
PUT /macaddrs/xx:xx:xx:xx:xx:xx?generate_dhcp=boolean Sets the generate DHCP flag for the specified mac addr

Deletes

DELETE /macaddrs/xx:xx:xx:xx:xx:xx Deletes the specified macaddr

Examples

Return a list of items which have hostnames matching gala%.inf.ed.ac.uk

curl -X GET -H 'Content-Type: text/x-json' https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/items?hostname='gala%.inf.ed.ac.uk'

will return

{"25441":{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/items/25441"},"24612":{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/items/24612"},"25442":{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/items/25442"},"27559":{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/items/27559"},"7380":{"url":"https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/items/7380"}}

Return information on item with item-id = 7380

curl -X GET -H 'Content-Type: text/x-json' https://tartarus.inf.ed.ac.uk/cgi-bin/orest/rest/items/7380

will return

{"allocated_type":"person","is_a_system":1,"model":null,"manual_location":null,"hostname":"gala.inf.ed.ac.uk","budget":"747DIV/G40588","os":null,"managed_type":"dice","disposal_extra":null,"last_seen":null,"category":"desktop","disposal_date":null,"cost":"330.88","parent":null,"make":null,"itemid":7380,"serial":"CZC2457YM0","purchase":{"vat":"1.2","supplier":"HP","purchase_order":"UOE54404"},"allocated_to":{"sname":"Scobie","uun":"ascobie","primaryrole":"Computing","cname":"Alastair"},"description":"HP 8300CMT i5 3.2GHz, 8GB, 500GB","location":"IF-5.14","delivered_date":"2012-11-19","manager":"ascobie@inf.ed.ac.uk","disposal_type":null,"warranty":"3yr","purchaseorder":"UOE54404"}

Mark item 7380 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/rest/rest/items/7380?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

Notes to self...

-- AlastairScobie - 23 May 2016

Topic attachments
I Attachment Action Size Date Who Comment
elseEXT lwpquery manage 1.6 K 15 Dec 2016 - 16:11 AlastairScobie A sample perl script to query the REST api
Topic revision: r34 - 06 Apr 2017 - 15:46:03 - AlastairScobie
 
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