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
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 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: r39 - 27 Nov 2017 - 18:24:46 - StephenQuinney
 
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