The Alveo API provides access to resources from the Alveo platform in a machine readable format (JSON). At present the API supports retrieving Item Lists, Items, Documents and Collection level metadata; it does not support creating Item Lists. It is assumed that a user will create an Item List via the Web Application and then can write code to access the Item List and individual Items for processing.

Using the API

All requests to the API must be authenticated using an API key which can be downloaded from the Web Application (click on your email address on the Navigation Bar and select API Key). The API key is specific to a user and should not generally be included in code that is published. (We are developing a standard configuration file location that can be used to store this).

The API Key needs to be specified as X-API-KEY in the request header. The API uses the same URLs as the main web application in most cases but is able to return data in JSON format when an appropriate Accept header is sent with the request. If the Accept header is set to ‘application/json’ or is left blank, then the response will be sent back as JSON. Alternatively, a ‘.json’ extension can be added to the end of the URL to force JSON format. A web browser will generally have a very broad Accept header that will include text/html and so will get an HTML response.

Examples

Command line:

1
2
3
4

Where  is the vlab host, e.g. https://app.alveo.edu.au/
$ curl -H "X-API-KEY: WUqhKgM25PJuzivjdvGt" /item_lists.json
$ curl -H "X-API-KEY: WUqhKgM25PJuzivjdvGt" -H "Accept: application/json" item_lists

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

    import pycurl
    import cStringIO
    import json

    api_key = YOUR_X_API_KEY>
    url = YOUR_URL> # e.g.: https://app.alveo.edu.au/item_lists/1

    curl = pycurl.Curl()
    buf = cStringIO.StringIO()
    curl.setopt(curl.URL, url)
    curl.setopt(pycurl.HTTPHEADER, ['X-API-KEY: ' + api_key, 'Accept: application/json'])
    curl.setopt(curl.WRITEFUNCTION, buf.write)
    curl.perform()
    response = buf.getvalue()
    status = curl.getinfo(pycurl.HTTP_CODE) 
    response = json.loads(string)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

    require 'net/http'
    require 'json'

    api_key = YOUR_X_API_KEY>
    url = YOUR_URL> # e.g.: https://app.alveo.edu.au/item_lists/1

    sampleUrl = URI(url)
    req = Net::HTTP::Get.new(sampleUrl)
    req['X-API-KEY'] = YOUR_X_API_KEY>
    req['Accept'] = "application/json"

    response = Net::HTTP.start(sampleUrl.hostname, sampleUrl.port) {|http|
      http.request(req)
    }

    jsonResponse = JSON.parse(res.body)