Alveo Documentation: HTTP API Reference

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:

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

Python

    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)

Ruby

    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)

HTTP Response Codes

Scenario	HTTP Response Code
User is unathenticated	401
User is unauthorised	403
User is authorised and the requested data is returned	200
User is authorised but the requested data is not found	404
Request uses bad syntax/missing required parameters	400

API Description

Description	URL	Method	Returns	Notes
Get API version	/version	GET	API version
Example Response	`{“API version”:”V2.0″}`
Get item lists	/item_lists	GET	Item Lists of the user (name, url, number of items)
Example Response	`[ { "name":"Jared's Item List 1", "item_list_url":"https://app.alveo.edu.au/item_lists/5", "num_items":1 }, { "name":"Jared's Item List 2", "item_list_url":"https://app.alveo.edu.au/item_lists/15", "num_items":3 }, { "name":"Jared's Item List 3", "item_list_url":"https://app.alveo.edu.au/item_lists/16", "num_items":3 } ]`
Get Items from Item List	/item_lists/{id}	GET	Specified Item List of the user (name, list of items)	Item list can be retrieved as JSON, ZIP or WARC format. The JSON format will only return the URL for the items in the Item list as shown below. The ZIP and WARC file will create a package containing the documents and metadata of the items in the Item list. The Zip file will respect the BagIt structure. Requests example: curl -H “X-API-KEY: <key>” -H “Accept: application/<format>” <server>/item_lists/{id} format= json or zip or warc
Example Response	`{ "name":"Jared's Item List 2", "num_items":3, "items":[ "https://app.alveo.edu.au/catalog/cooee/2-037", "https://app.alveo.edu.au/catalog/cooee/2-038", "https://app.alveo.edu.au/catalog/cooee/2-040" ] ] }`
Delete Item List	/item_lists/{id}	DELETE	Specified Item List of the user (name, list of items)	Item list can be deleted via HTTP DELETE mehod with the same endpoint as get items from item list Requests example: curl -X DELETE -H “X-API-KEY: <key>” -H “Accept: application/json” <server>/item_lists/{id}
Example Response	`{ "success":"item list test deleted successfully" }`
Share Item List	/item_lists/{id}/share	POST	Specified Item List of the user (name, list of items)	Item list can be shareed via HTTP POST mehod Requests example: curl -X POST -d “” -H “X-API-KEY: <key>” -H “Accept: application/json” <server>/item_lists/{id}/share
Example Response	`{ "success":"Item list test is shared. Any user in the application will be able to see it." }`
Unshare Item List	/item_lists/{id}/unshare	POST	Specified Item List of the user (name, list of items)	Item list can be unshareed via HTTP POST mehod Requests example: curl -X POST -d “” -H “X-API-KEY: <key>” -H “Accept: application/json” <server>/item_lists/{id}/unshare
Example Response	`{ "success":"Item list test is not being shared anymore." }`
Clear Item List	/item_lists/{id}/clear	POST	Specified Item List of the user (name, list of items)	Item list can be unshareed via HTTP POST mehod Requests example: curl -X POST -d “” -H “X-API-KEY: <key>” -H “Accept: application/json” <server>/item_lists/{id}/clear
Example Response	`{ "success":"2 cleared from item list test" }`
Get item metadata	/catalog/{collection_name}/{item_id}	GET	Item Metadata, primary text URL & document URLs
Example Response	{ "@context": "https://app.alveo.edu.au/schema/json-ld", "alveo:catalog_url": "https://app.alveo.edu.au/catalog/ace/A08g", "alveo:metadata": { "dc:title": "Boy Drowns Trying to Save Pet Dog", "dc:created": "8 September 1986", "dc:identifier": "A08g", "dc:isPartOf": "ace", "ausnc:itemwordcount": "110", "ausnc:mode": "written", "ausnc:speech_style": "unspecified", "ausnc:interactivity": "unspecified", "ausnc:communication_context": "unspecified", "olac:discourse_type": "unspecified", "olac:language": "eng", "ace:genre": "Press Reportage", "ausnc:audience": "mass_market", "ausnc:communication_setting": "popular", "ausnc:communication_medium": "unspecified", "ausnc:publication_status": "published", "ausnc:source": "The Sun 8 September 1986 (2001 words)", "ausnc:written_mode": "print", "dc:publisher": "Publisher - John Fairfax and Sons Ltd", "ausnc:document": "A08g#Text, A08g#Original, A08g#Raw", "dc:type": "Text, Original, Raw", "dc:extent": "631, 579959, 739", "alveo:date_group": "1980 - 1989", "alveo:display_document": "A08g#Text", "alveo:indexable_document": "A08g#Text", "alveo:full_text": "BOY DROWNS TRYING TO SAVE PET DOG A BOY drowned...", "alveo:handle": "ace:A08g", "alveo:sparqlEndpoint": "https://app.alveo.edu.au/sparql/ace" }, "alveo:primary_text_url": "https://app.alveo.edu.au/catalog/ace/A08g/primary_text.json", "alveo:annotations_url": "https://app.alveo.edu.au/catalog/ace/A08g/annotations.json", "alveo:documents": [{ "alveo:url": "https://app.alveo.edu.au/catalog/ace/A08g/document/A08g-plain.txt", "dc:type": "Text", "alveo:size": "631 B", "rdf:type": "http://xmlns.com/foaf/0.1/Document", "dc:identifier": "A08g-plain.txt", "dc:title": "A08g#Text", "dc:extent": "631", "dc:type": "Text" }, { "alveo:url": "https://app.alveo.edu.au/catalog/ace/A08g/document/ace_a.txt", "dc:type": "Original", "alveo:size": null, "rdf:type": "http://xmlns.com/foaf/0.1/Document", "dc:identifier": "ace_a.txt", "dc:title": "A08g#Original", "dc:extent": "579959", "dc:type": "Original" }, { "alveo:url": "https://app.alveo.edu.au/catalog/ace/A08g/document/A08g-raw.txt", "dc:type": "Raw", "alveo:size": "739 B", "rdf:type": "http://xmlns.com/foaf/0.1/Document", "dc:identifier": "A08g-raw.txt", "dc:title": "A08g#Raw", "dc:extent": "739", "dc:type": "Raw" }] }
Get primary text	/catalog/{collection_name}/{item_id}/primary_text	GET	Content of item’s primary_text	This starts a download using the primary_text content with the filename as the label attached during ingest.
Get document	/catalog/{collection_name}/{item_id}/document/{filename} Example: /catalog/ace/A08g/document/A08g-raw.txt	GET	Specified document that belongs to the Item	This sends the file as listed in the SOURCE metadata. Note: The filename is being passed as a url parameter, which allows us to have the unified devise error handling that comes with a .json response
Get annotation context	/schema/json-ld	GET	Context for the annotations	Static conext linked from the annotations API call
Example Response	{ "@context": { "@base":"http://purl.org/dada/schema/0.2/", "annotations":{ "@id":"http://purl.org/dada/schema/0.2/annotations", "@container":"@list" }, "commonProperties": {"@id":"http://purl.org/dada/schema/0.2/commonProperties"}, "type":{"@id":"http://purl.org/dada/schema/0.2/type"}, "start":{"@id":"http://purl.org/dada/schema/0.2/start"}, "end":{"@id":"http://purl.org/dada/schema/0.2/end"}, "label":{"@id":"http://purl.org/dada/schema/0.2/label"}, "annotates":{"@id":"http://purl.org/dada/schema/0.2/annotates"} } }
Get annotations	/catalog/{collection_name}/{item_id}/annotations /catalog/{collection_name}/{item_id}/annotations.json?type=maus:phonetic&label=s	GET	Annotations from this item’s annotation file	Queries the item’s annotation file for all annotations (label, start/end times). Type and label can be passed in to narrow the query
Example Response	{ @context: "https://app.alveo.edu.au/schema/json-ld", commonProperties: { alveo: annotates: "https://app.alveo.edu.au/catalog/mitcheldelbridge/S1224s1/document/S1224s1.wav" }, alveo: annotations: [{@ id: "http://ns.ausnc.org.au/corpora/mitcheldelbridge/annotation/302021", label: "s", type: "http://ns.ausnc.org.au/schemas/annotation/maus/phonetic", @type: "dada:SecondAnnotation", end: "2.21", start: "2.18" }, {@ id: "http://ns.ausnc.org.au/corpora/mitcheldelbridge/annotation/302024", label: "s", type: "http://ns.ausnc.org.au/schemas/annotation/maus/phonetic", @type: "dada:SecondAnnotation", end: "3.31", start: "3.28" }] }
Get annotation types	/catalog/{collection_name}/{item_id}/annotations/types	GET	Annotation types from this item’s annotations	Queries the item’s annotations to return all the different annotation types for the item
Example Response	{ item_url: "https://app.alveo.edu.au/catalog/cooee:4-340", annotation_types: [ "http://ns.ausnc.org.au/schemas/annotation/cooee/ellipsis", "http://ns.ausnc.org.au/schemas/annotation/cooee/pageno" ] }
Get items’ documents and metadata	/catalog/download_items	POST	Download a file in the specified format containing the item’s documents and metadata	This is a post request that requires a JSON set of items sent with it. Hence, cannot be replicated through a browser but through curl this can be done with something akin to: `curl -H "X-API-KEY: <key>" -H "Accept: application/<format>" -H "Content-Type: application/json" -X POST -d '{"items":["<host>/catalog/cooee/2-015","<host>/catalog/cooee/2-021"]}' <host>/catalog/download_items` Allowed formats = zip, warc. If format is not specified, zip will be set by default You can also specify the file format using as follow: `curl -H "X-API-KEY: <key>" -H "Content-Type: application/json" -X POST -d '{"items":["<host>/catalog/cooee/2-015","<host>/catalog/cooee/2-021"]}' <host>/catalog/download_items.<format>` `curl -H "X-API-KEY: <key>" -H "Content-Type: application/json" -X POST -d '{"items":["<host>/catalog/cooee/2-015","<host>/catalog/cooee/2-021"]}' <host>/catalog/download_items?format=<format>` To save the retrieved zip file the API call output needs to be redirected to a file. This can be achieved using the ‘&gt’ character at the end of the API call similar to the following: `"X-API-KEY: <key>" -H "Accept: application/<format>" -H "Content-Type: application/json" -X POST -d '{"items":["<host>/catalog/cooee/2-015","<host>/catalog/cooee/2-021"]}' <host>/catalog/download_items > items.zip` A document filter can be applied to limit the type of item documents downloaded. This is used by providing a glob to the JSON parameter `doc_filter`. If no glob filter is provided then this API call will download all item documents by default. Note that Glob is used for filtering rather than Regular Expressions. This affects usage as the syntax for glob and regex are similar but different (i.e. a valid regex is not always a valid glob). Basic glob syntax can be found on wikipedia: https://en.wikipedia.org/wiki/Glob_(programming) The exact syntax as used in implementation: http://ruby-doc.org/core-2.2.0/File.html#method-c-fnmatch Some example globs are: .wav .txt -raw.txt myDocument. *.{wav,mp3}
Example Input	`{ "items":[ "https://app.alveo.edu.au/catalog/cooee/2-036", "https://app.alveo.edu.au/catalog/cooee/2-037", "https://app.alveo.edu.au/catalog/cooee/2-038", "https://app.alveo.edu.au/catalog/cooee/2-040" ], "doc_filter":".txt" }` Another way to download, using Aspera Connect secure download, (Aspera will prompt user to download Aspera Connect if user doesn't already have it) Example Aspera transfer download API call: `curl -H "X-API-KEY: <key>" -H "Content-Type: application/json" -X POST -d '{"doc_filter":".txt"}' <serverurl>/item_lists/3/aspera_transfer_spec`
Get collections list	/catalog	GET	Number of collections, and collections list
Example Response	`{ "num_collections":6, "collections":[ "https://app.alveo.edu.au/catalog/ace", "https://app.alveo.edu.au/catalog/austlit", "https://app.alveo.edu.au/catalog/cooee", "https://app.alveo.edu.au/catalog/gcsause", "https://app.alveo.edu.au/catalog/ice", "https://app.alveo.edu.au/catalog/monash" ] }`
Get collection	/catalog/{collection_name}	GET	Collection url, name and metadata
Example Response	`{ "collection_url":"https://app.alveo.edu.au/catalog/monash", "collection_name":"monash", "metadata": { "RDF_type":"Collection", "Is Located At":"Monash University, Victoria, Australia", "Custodian":"simon Musgrave", "Rights":"All rights reserved to Monash UNiversity", "Subject":"2004 - Linguistics", "Title":"Monash Corpus of Spoken English" ... (other fields) } }`
Search Metadata	/catalog/search?metadata=<query> Example: /catalog/search?metadata=collection_name:cooee	GET	List of search results
Example Response	`{ "num_results":4, "items":[ "https://app.alveo.edu.au/catalog/cooee/2-036", "https://app.alveo.edu.au/catalog/cooee/2-037", "https://app.alveo.edu.au/catalog/cooee/2-038", "https://app.alveo.edu.au/catalog/cooee/2-040" ] }`
Add to item list	/item_lists /item_lists?name=ItemListA	POST	Result of item list operation (error/success)	This is a post request that requires a JSON set of items sent with it. Hence, cannot be replicated through a browser but through curl this can be done with something akin to: curl -H “X-API-KEY: ” -H “Content-Type: application/json” -H “Accept: application/json” -X POST -d ‘{“num_results”:2,”items”:[“/catalog/cooee/2-015″,”/catalog/cooee/2-021″]}’ /item_lists?name=A Note: the name doesn’t have to be sent in as a parameter attached to the URL, it can also be sent in as part of the JSON
Example Input	`{ "name":"New Item List", "num_results":4, "items":[ "https://app.alveo.edu.au/catalog/cooee/2-036", "https://app.alveo.edu.au/catalog/cooee/2-037", "https://app.alveo.edu.au/catalog/cooee/2-038", "https://app.alveo.edu.au/catalog/cooee/2-040" ] ] }` OR if name is specified as url parameter as shown in the notes above `{ "items":[ "https://app.alveo.edu.au/catalog/cooee/2-036", "https://app.alveo.edu.au/catalog/cooee/2-037", "https://app.alveo.edu.au/catalog/cooee/2-038", "https://app.alveo.edu.au/catalog/cooee/2-040" ] ] }`
Example Response	`Success: {"success":"2 items added to existing item list A"} Failure: {"error":"name parameter not found"} or {"error":"items parameter not found"} or {"error":"items parameter not an array"} or {"error":"invalid-json"}`
Rename Item List	/item_lists/{item_list_id}	PUT	Item list if successful/error message if failure	This is a put request that takes the new name of the item list. Example curl command: curl -H “X-API-KEY:<api_key>” -H “Accept: application/json” -X PUT -d ‘{“name”:”<new name>”}’ <host>/item_lists/:id
Example Response	`Success: { "name":"Jared's Item List 2", "num_items":3, "items":[ "https://app.alveo.edu.au/catalog/cooee/2-037", "https://app.alveo.edu.au/catalog/cooee/2-038", "https://app.alveo.edu.au/catalog/cooee/2-040" ] ] } Failure: {"error":"name can't be blank"} or {"error":"name too long"} or {"error":"couldn't rename item list"}`
Upload Annotation	/catalog/{collection_name}/{item_id}/annotations	POST	Result of item list operation (error/success)	This is a post request that requires a file sent with it. Hence, cannot be replicated through a browser but through curl this can be done with something akin to: curl -H “X-API-KEY:<api_key>” -H “Accept: application/json” -F file=@<path_to_file> <host>/catalog/:id/annotations
Json-Ld Input File format	`{ "@context": { "@base": "http://purl.org/dada/schema/0.2/", "": { "@id": "" }, "": { "@id": "" }, . . . "": { "@id": "" }, }, "@graph":[ { "@type": "http://purl.org/dada/schema/0.2#UTF8Region", "": "value", "": "value", . . . "": "value", }, { "@type": "http://purl.org/dada/schema/0.2#UTF8Region", "": "value", "": "value", . . . "": "value", }, . . . { "@type": "http://purl.org/dada/schema/0.2#UTF8Region", "": "value", "": "value", . . . "": "value", } ] }`
Example Response	`Success: {"success":"file <filename> uploaded successfully"} Failure: {"error":"No Item with id '<item_id>' exists."} or {"error":"Uploaded file is not present or empty."} or {"error":"File already uploaded."} or {"error":"Error uploading file <filename>."}`
Query metadata and annotations usign sparql	/sparql/<collection-name>?query=<sparql-query>	GET	Json formatted query result	curl -g -H “X-API-KEY: <API_KEY>” -H “Accept: application/json” “<host>/sparql/<collection-name>?query=<sparql-query>” Example: curl -g -H “X-API-KEY: <API_KEY>” -H “Accept: application/json” “<host>/sparql/cooee?query=select * where {?s <http://purl.org/dc/terms/isPartOf> ?o}” (e.g.curl -H “X-API-KEY:” -H “Content-Type: application/json” -H “Accept: application/json” https:///licences
Example Response	{ "head" : { "vars" : [ "s", "o" ] }, "results" : { "bindings" : [ { "s" : { "type" : "uri", "value" : "http://ns.ausnc.org.au/corpora/cooee/items/1-001" }, "o" : { "type" : "uri", "value" : "http://ns.ausnc.org.au/corpora/cooee" } }, { "s" : { "type" : "uri", "value" : "http://ns.ausnc.org.au/corpora/cooee/items/1-002" }, "o" : { "type" : "uri", "value" : "http://ns.ausnc.org.au/corpora/cooee" } }, { "s" : { "type" : "uri", "value" : "http://ns.ausnc.org.au/corpora/cooee/items/1-003" }, "o" : { "type" : "uri", "value" : "http://ns.ausnc.org.au/corpora/cooee" } }] } }
Get licences	/licences	GET	List of licences in the system, their name and ID
Example Response	`[ { "name":"Creative Commons", "id": 1 }, { "name":"AusNC Terms of Use", "id": 2 }, { "name":"Creative Commons V3", "id": 3 } ]`
Create a collection	/catalog	POST	Result of operation (error/success)	Users are only authorised to create a collection if they have the role of ‘admin’ or ‘data owner’. The collection name can either be supplied as a JSON parameter or as a URL paramaeter. See the example input for examples of this. A licence can be assigned to the collection by passing in the `licence_id` parameter. As with the collection name, this can either be supplied as a JSON parameter or as a URL parameter. Collection privacy can be set to change whether or not approval is required for other users to access the collection, by passing in the `private` parameter set to either `true` or `false`. By default this is set to true so that approval is required for collection access. As with the collection name and licence, this can either be supplied as a JSON parameter or as a URL parameter. This is a POST request that requires a JSON-LD set of collection metadata to be sent with it. Hence, cannot be replicated through a browser but through curl this can be done with something akin to the following: When creating a collection with the collection name supplied as a URL parameter: `curl -X POST -H "X-API-KEY: <key>" -H "Content-Type: application/json" -H "Accept: application/json" -d '{ "collection_metadata": <collection_metadata>}' '<server>/catalog?name=<collection_name>&licence_id=1&private=true'` When creating a collection with the collection name supplied as a JSON parameter: `curl -X POST -H "X-API-KEY: <key>" -H "Content-Type: application/json" -H "Accept: application/json" -d '{ "collection_metadata": <collection_metadata>, "name":"<collection_name>", "licence_id":1, "private":true}' <server>/catalog`
Example Input	The following is an example of expected input for &ltcollection_metadata&gt: `{ "@context": { "dc": "http://purl.org/dc/terms/", "dcterms": "http://purl.org/dc/terms/", "dcmitype": "http://purl.org/dc/dcmitype/" }, "@type": "dcmitype:Collection", "dc:creator": "Data Owner", "dc:rights": "All rights reserved to Data Owner", "dc:subject": "English Language", "dc:title": "Test" }`
Example Response	Success: {“success”:”New collection ‘&ltcollection_name&gt’ (&ltcollection_URI&gt) created”} Failure: {“error”:”Permission Denied: Your role within the system does not have sufficient privileges to be able to create a collection. Please contact an Alveo administrator.”} or {“error”:”name parameter not found”} or {“error”:”metatdata parameter not found”} or {“error”:”name and metadata parameters not found”} or {“error”:”invalid-json”} or {“error”:”JSON-LD formatted metadata must be sent to the add collection api call as a POST request”} or {“error”:”Collection ‘&lcollection_namet&gt’ (&ltcollection_URI&gt) already exists in the system – skipping”}
Edit a Collection	/catalog/{collection_name}	PUT	Result of operation (error/success)	Notes: Users are only authorised to edit a collection which they own. It is not neccessary to include the collection URI within the JSON-LD metadata `("@id":"<collection_uri>")` as this will be automatically generated. The “replace” JSON parameter indicates whether or not the provided metadata should replace the existing collection metadata. If replace is true then the entire existing collection metadata (including the context) will be replaced with the provided metadata. If replace is false or unsupplied then the collection metadata will be updated with the provided metadata. This is a PUT request. Hence, cannot be replicated through a browser but through curl this can be done with something akin to the following. `curl -H "X-API-KEY: <key>" -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d '{ "replace": <true/false>, "collection_metadata": <collection_metadata>}' <server>/catalog/<collection_id>`
Example Input	When updating collection metadata without specifying the “replace” parameter: `{ "collection_metadata": {"http://purl.org/dc/elements/1.1/title": "An updated test collection"}}` When updating collection metadata by setting the “replace” parameter to false: `{ "replace": false, "collection_metadata": {"http://purl.org/dc/elements/1.1/title": "An updated test collection"}}` When overwriting collection metadata by setting the “replace” parameter to true: `{ "replace": true, "collection_metadata": {"@context": {"dc": "http://purl.org/dc/elements/1.1/", "dcmitype": "http://purl.org/dc/dcmitype/"}, "@type": "dcmitype:Collection", "dc:title": "An updated test collection", "dc:subject": "English Language", "dc:creator": "Test User"}}`
Example Response	Success: {“success”:”Updated collection &ltcollection_name&gt”} Failure: {“error”:”Requested collection not found”} or {“error”:”User is unauthorised”} or {“error”:”Invalid metadata”}
Add items with documents to an owned collection	/catalog/{collection_id}	POST	Result of operation (error/success) and a list of item ids for each item added	Notes: Users are only authorised to add items to a collection which they own. The expected format for adding a document is to have the metadata for that document nested within the item level metadata. See the example input for examples of this. When adding items or documents, the “@id” that specifies the URI of the item/document needs to be supplied. This will then be automatically converted into Alveo catalog URLs. For example: When adding an item to a test collection if the user specifies `"@id":"item1"` then the system will convert this into `"@id":"http://app.avleo.edu.au/catalog/test/item1"`. Similarly a document with `"@id":"document1"` will be converted to `"@id":"http://app.alveo.edu.au/catalog/test/item1/document/document1"`. The document metadata term `"dcterms:source":{"@id":"<file_or_http_uri>"}` does not need to be provided for any documents whose contents are embedded in the JSON item metadata or are uploaded as part of the HTTP request. This is since the server will assign a location for uploaded documents and modify the aforementioned metadata document source term appropriately. However it is essential to include the document source metadata term for any documents referenced with “file://” or “http://”. For document files referenced with “file://” or “http://” the file basename (filename and extension) must match the `"dcterms:identifier"` of that document. For example, if referencing the file `"dcterms:source":{"@id":"file:///data/directory/example.txt"}` then it is expected that the identifier of that document will be `"dcterms:identifier":"example.txt"` For document files uploaded as part of the HTTP request or whose content is embedded in the JSON item metadata, for that document content or file to be associated with the metadata of a particular document the value given to the `"dcterms:identifier"` within the document metadata needs to match the name of the uploaded file or identifier of the embedded document content. For example: a document with metadata containing `"dcterms:identifier":"sample.txt"` will be associated with the uploaded file “sample.txt”. The `"dcterms:isPartOf":{"@id":"corpus:<collection_name>"}` should not be supplied when adding an item to a collection. This metadata will be automatically generated and will correspond with the collection that the item is being added to. If this metadata is supplied it will be overwritten when the system generates it for the corresponding corpus. If an item being added contains invalid metadata that item will not be added to the collection but all other valid items shall continue to be added to the collection. The API response will contain a list of ids of each item that was successfully added to the collection. This is a POST request that requires a JSON-LD set of collection metadata to be sent with it. Hence, cannot be replicated through a browser but through curl this can be done with something akin to the following: If adding an item with document(s) that are referenced (with “file://” or “http://”): `curl -X POST -H "X-API-KEY: <key>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"items":[{"metadata":{<item_metadata>}'}]}' <server>/catalog/<collection_id>` If adding an item with document(s) whose contents are embedded in the JSON item metadata: `curl -X POST -H "X-API-KEY: <key>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"items":[{"documents":[{<document_metadata>}], "metadata":{<item_metadata>}'}]}' <server>/catalog/<collection_id>` If adding an item with a single document uploaded as part of the HTTP request: `curl -X POST -H "X-API-KEY: <key>" -H "Accept: application/json" -F file=@"<file_location>" -F items='[{<item_metadata>}]' <server>/catalog/<collection_id>` If adding an item with multiple documents uploaded as part of the HTTP request: `curl -X POST -H "X-API-KEY: <key>" -H "Accept: application/json" -F file[]=@"<file_1_location>" -F file[]=@"<file_2_location>" -F items='[{<item_metadata>}]' <server>/catalog/<collection_id>`
Example Input	If adding an item with document(s) that are referenced (with “file://” or “http://”): -d '{ "items": [ { "metadata": { "@context": { "ausnc": "http://ns.ausnc.org.au/schemas/ausnc_md_model/", "corpus": "http://ns.ausnc.org.au/corpora/", "dc": "http://purl.org/dc/terms/", "dcterms": "http://purl.org/dc/terms/", "foaf": "http://xmlns.com/foaf/0.1/", "hcsvlab": "http://hcsvlab.org/vocabulary/" }, "@graph": [ { "@id": "item1", "@type": "ausnc:AusNCObject", "ausnc:document": [ { "@id": "document1", "@type": "foaf:Document", "dcterms:extent": 1234, "dcterms:identifier": "document1.txt", "dcterms:source": { "@id": "file:///data/test_collections/ausnc/test/document2.txt" }, "dcterms:title": "document1#Text", "dcterms:type": "Text" } ], "dcterms:identifier": "item1", "hcsvlab:indexable_document": { "@id": "document1.txt" }, "hcsvlab:display_document": { "@id": "document1.txt" } } ] } } ] }' If adding an item with document(s) whose contents are embedded in the JSON item metadata: -d '{"items": [ { "documents": [ { "identifier": "document1.txt", "content": "This document had its content provided as part of the JSON request." } ], "metadata": { "@context": { "ausnc": "http://ns.ausnc.org.au/schemas/ausnc_md_model/", "corpus": "http://ns.ausnc.org.au/corpora/", "dc": "http://purl.org/dc/terms/", "dcterms": "http://purl.org/dc/terms/", "foaf": "http://xmlns.com/foaf/0.1/", "hcsvlab": "http://hcsvlab.org/vocabulary/" }, "@graph": [ { "@id": "item1", "@type": "ausnc:AusNCObject", "ausnc:document": [ { "@id": "document1.txt", "@type": "foaf:Document", "dcterms:extent": 72636, "dcterms:identifier": "document1.txt", "dcterms:title": "document1#Text", "dcterms:type": "Text" } ], "dcterms:identifier": "item1", "hcsvlab:display_document": { "@id": "document1.txt" }, "hcsvlab:indexable_document": { "@id": "document1.txt" } } ] } } ] }' If adding an item with a single document uploaded as part of the HTTP request: -F file=@"1-001-plain.txt" -F items='[ { "metadata": { "@context": { "ausnc": "http://ns.ausnc.org.au/schemas/ausnc_md_model/", "corpus": "http://ns.ausnc.org.au/corpora/", "dc": "http://purl.org/dc/terms/", "dcterms": "http://purl.org/dc/terms/", "foaf": "http://xmlns.com/foaf/0.1/", "hcsvlab": "http://hcsvlab.org/vocabulary/" }, "@graph": [ { "@id": "item1", "@type": "ausnc:AusNCObject", "ausnc:document": [ { "@id": "1-001-plain.txt", "@type": "foaf:Document", "dcterms:extent": 72636, "dcterms:identifier": "1-001-plain.txt", "dcterms:title": "document1#Text", "dcterms:type": "Text" } ], "dcterms:identifier": "item1", "hcsvlab:display_document": { "@id": "1-001-plain.txt" }, "hcsvlab:indexable_document": { "@id": "1-001-plain.txt" } } ] } } ]'
Example Response	Success: {“success”:[“&ltitem_1_id&gt”, “&ltitem_2_id&gt”]} or {“success”:[“&ltitem_id&gt”], “failures”:[“Unknown item contains invalid metadata”]} Failure: {“error”:”JSON-LD formatted item metadata must be sent with the api request”} or {“error”:”JSON item metadata is ill-formatted”} or {“error”:”Requested collection not found”} or {“error”:”User is unauthorised”} or {“error”:”The item &ltitem_id&gt already exists in the collection &ltcollection_name&gt”} or {“error”:”identifier missing from document”} or {“error”:”The identifier “&ltdocument_id&gt” is used for multiple documents”} or {“error”:”content missing from document &ltdocument_id&gt”} or {“error”:”The file &ltfilename&gt has already been uploaded to the collection &ltcollection_name&gt”} or {“error”:”Error in file parameter.”} or {“error”:”Uploaded file is not present or empty.”} or {“error”:”No items were added”}
Update an item	/catalog/{collection_name}/{item_name}	PUT	Result of operation (error/success)	Notes: Users are only authorised to update an item from collection which they own. This is a PUT request. Hence, cannot be replicated through a browser but through curl this can be done with something akin to the following. `curl -H "X-API-KEY: <key>" -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d '{"metadata": <item_metadata>}' <server>/catalog/<collection_id>/<item_id>`
Example Input	The following is an example of expected input for &ltitem_metadata&gt: `{"http://ns.ausnc.org.au/schemas/ausnc_md_model/mode":"An updated test mode"}` `{"@context":{"ausnc":"http://ns.ausnc.org.au/schemas/ausnc_md_model/"}, "ausnc:speech_style":"An updated speech style"}`
Example Response	Success: {"success":"Updated item <item_id> in collection <collection_id>"} Failure: {"error":"Requested collection not found"} or {"error":"Requested item not found"} or {"error":"User is unauthorised"} or {"error":"Invalid metadata"}
Delete an item from an owned collection	/catalog/{collection_id}/{item_id}	DELETE	Result of operation (error/success)	Notes: Users are only authorised to delete an item from collection which they own. Deleting an item from a collection also deletes all of that items documents and the corresponding document audits. This is a DELETE request. Hence, cannot be replicated through a browser but through curl this can be done with something akin to the following. `curl -H "X-API-KEY: <api_key>" -H "Accept: application/json" -X DELETE <server>/catalog/<collection_id>/<item_id>`
Example Response	Success: {"success":"Deleted the item <item_id> (and its documents) from collection <collection_id>"} Failure: {"error":"User is unauthorised"} or {"error":"Requested collection not found"} or {"error":"Requested item not found"}
Add a document to an owned item	/catalog/{collection_id}/{item_id}	POST	Result of operation (error/success)	Notes: Users are only authorised to add documents to existing items in collections which they own. When adding a document a shortened form of the "@id" which specifies the document URI needs to be supplied. This will be automatically converted into Alveo catalog URLs. For example, if adding a document named "document1.txt" then the shortened document URI `"@id":"document1.txt"` should be supplied and will be automatically converted to `"@id":"http://app.alveo.edu.au/catalog/test/item1/document/document1"`. The identifiers in the supplied document metadata should have matching values, specifically the "@id" and the "dcterms:identifier" or "dc:identifier". This also applies to the document filename if a file is uploaded or a referenced file is used. When uploading files or including the document content as JSON the document source metadata `"dcterms:source":{"@id":"<file_or_http_uri>"}` does not need to be supplied. Instead the system will automatically assign a location for these document files and generate this metadata accordingly. However it is essential to include the document source metadata term for any documents referenced with "file://" or "http://". This is a POST request that requires a JSON-LD set of document metadata to be sent with it. Hence, cannot be replicated through a browser but through curl this can be done with something akin to the following. If adding a a document referenced (with "file://" or "http://"): `curl -X POST -H "X-API-KEY: <key>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"metadata":{<idocument_metadata>}' <server>/catalog/<collection_id>/<item_id>` If adding a document whose content is embedded in JSON: `curl -X POST -H "X-API-KEY: <key>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"document_content": "<document_content>", "metadata":{<document_metadata>}' <server>/catalog/<collection_id>/<item_id>` If adding an item with a single document uploaded as part of the HTTP request: `curl -X POST -H "X-API-KEY: <key>" -H "Accept: application/json" -F file=@"<file_location>" -F metadata='{<document_metadata>}' <server>/catalog/<collection_id>/<item_id>`
Example Input	If adding a document referenced (with "file://" or "http://"): `-d '{ "metadata": { "@context": { "dcterms": "http://purl.org/dc/terms/", "foaf": "http://xmlns.com/foaf/0.1/" }, "@id": "document2.txt", "@type": "foaf:Document", "dcterms:identifier": "document2.txt", "dcterms:title": "document2#Text", "dcterms:type": "Text", "dcterms:source": { "@id": "file:///data/test_collections/ausnc/test/document2.txt" } } }'` If adding a document whose contents are embedded in the JSON: `-d '{ "document_content": "Hello World!", "metadata": { "@context": { "dcterms": "http://purl.org/dc/terms/", "foaf": "http://xmlns.com/foaf/0.1/" }, "@id": "document2.txt", "@type": "foaf:Document", "dcterms:identifier": "document2.txt", "dcterms:title": "document2#Text", "dcterms:type": "Text" } }'` If adding a document uploaded as part of the HTTP request: `-F file=@"document2.txt" -F metadata='{ "@context": { "dcterms": "http://purl.org/dc/terms/", "foaf": "http://xmlns.com/foaf/0.1/" }, "@id": "document2.txt", "@type": "foaf:Document", "dcterms:identifier": "document2.txt", "dcterms:title": "document2#Text", "dcterms:type": "Text" }'`
Example Response	Success: {"success":"Added the document <document_filename> to item <item_id> in collection <collection_id>"} Failure: {"error":"User is unauthorised"} or {"error":"Requested collection not found"} or {"error":"Requested item not found"} or {"error":"JSON-LD formatted item metadata must be sent with the api request"} or {"error":"JSON item metadata is ill-formatted"} or {"error":"The document <document_id> already exists in the collection <collection_name>"} or {"error":"content missing from document <document_id>"} or {"error":"The file <filename> has already been uploaded to the collection <collection_name>"} or {"error":"Error in file parameter."} or {"error":"Uploaded file is not present or empty."}
Delete a document from an owned item	/catalog/{collection_id}/{item_id}/document/{document_filename}	DELETE	Result of operation (error/success)	Notes: Users are only authorised to delete documents from items in collections which they own. If the source for the document is a file, e.g. on upload was sourced at: { "dcterms:source": { "@id": "file:///home/devel/<file_name>.txt"}, on API delete document call, the ORIGINAL SOURCE file is deleted. This is a DELETE request. Hence, cannot be replicated through a browser but through curl this can be done with something akin to the following. `curl -H "X-API-KEY: <api_key>" -H "Accept: application/json" -X DELETE <server>/catalog/<collection_id>/<item_id>/document/<document_filename>`
Example Response	Success: {"success":"Deleted the document <document_filename> from item <item_id> in collection <collection_id>"} Failure: {"error":"User is unauthorised"} or {"error":"Requested collection not found"} or {"error":"Requested item not found"} or {"error":"Requested document not found"}

HTTP API Reference