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

Until March 2018 there were two URLs - one unauthenticated, the other authenticated.

There is now only one, authenticated, URL - 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.
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).
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.../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

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 -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...

  • Supporting multiple API versions
    • client - 'ii' can read /etc/tartarus.conf to override the URL to the API
    • server
      • duplicate lib/REST as lib/REST-1
      • duplicate /usr/lib/tartarus/web/cgi-bin/orest/rest as /usr/lib/tartarus/web/cgi-bin/orest/rest-1 (which calls lib/REST-1)
  • TODO: add /spaces
  • TODO: add /persons (!)
  • TODO: add /reports
  • TODO: get /vms?vmhost=iid - return all VMs registered to the specified host (this isn't strictly speaking necessary as this information is returned as part of GET /items/{iid}
  • We are going to ignore pagination until it proves necessary
  • We might want http://tartarus/api/hostname/{hostname} as we're planning on hostnames being unique in the Inventory
  • credit these urls in the code somewhere - http://stackoverflow.com/questions/8493686/how-can-i-use-catalyst-and-uri-chaining-with-a-rest-interface and https://gist.github.com/mgcam/db91984da68daf74c175
  • PUT should be used for updates, POST for creating new records (Actually, you could use PUT for adding a macaddr because it shouldn't matter if the PUT is done twice)
  • Should we add a macaddress by doing a POST http://tartarus/api/items/{id}?macaddr={xx:xx:xx:xx:xx} or http://tartarus/api/items{id}/macaddr/{xx:xx:xx:xx:xx}
  • Should "cost" be VAT inclusive. (Arguably yes, otherwise folk will have to look up the VAT from the purchaseorder)
  • Need to decide what to do about status codes returned - still some question mark over this. This is particularly unclear for a PUT /item?allocated_to=uun where the 'uun' doesn't exist. Do you return 200 (with an 'error' value in a json string) or 400 (with an 'error' value in a json string). Apparently some APIs (https://www.bennadel.com/blog/2434-http-status-codes-for-invalid-data-400-vs-422.htm) use 422, but there isn't a status helper for 422 in catalyst-rest.
  • Modify so that 200 returns a status value to indicate success (so can distinguish between a successful return from tartarus and a successful return from an empty http server)

-- 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: r40 - 27 Mar 2018 - 14:20:13 - 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