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 '>' 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)
    1. Users are only authorised to create a collection if they have the role of 'admin' or 'data owner'.
    2. The collection name can either be supplied as a JSON parameter or as a URL paramaeter. See the example input for examples of this.
    3. 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.
    4. 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.
    5. 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 <collection_metadata>:

    • { "@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 '<collection_name>' (<collection_URI>) 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>' (<collection_URI>) already exists in the system - skipping"}
    Edit a Collection /catalog/{collection_name} PUT Result of operation (error/success) Notes:

    1. Users are only authorised to edit a collection which they own.
    2. It is not neccessary to include the collection URI within the JSON-LD metadata ("@id":"<collection_uri>") as this will be automatically generated.
    3. 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.
    4. 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 <collection_name>"}

    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:

    1. Users are only authorised to add items to a collection which they own.
    2. 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.
    3. 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".
    4. 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://".
    5. 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"
    6. 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".
    7. 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.
    8. 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.
    9. 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":["<item_1_id>", "<item_2_id>"]}

    or

    {"success":["<item_id>"], "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 <item_id> already exists in the collection <collection_name>"}

    or

    {"error":"identifier missing from document"}

    or

    {"error":"The identifier "<document_id>" is used for multiple documents"}

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

    or

    {"error":"No items were added"}
    Update an item /catalog/{collection_name}/{item_name} PUT Result of operation (error/success) Notes:

    1. Users are only authorised to update an item from collection which they own.
    2. 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 <item_metadata>:

    • {"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:
    1. Users are only authorised to delete an item from collection which they own.
    2. Deleting an item from a collection also deletes all of that items documents and the corresponding document audits.
    3. 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:

    1. Users are only authorised to add documents to existing items in collections which they own.
    2. 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".
    3. 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.
    4. 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://".
    5. 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:

    1. Users are only authorised to delete documents from items in collections which they own.
    2. 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.
    3. 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"}