API Design¶

The API for the InformaCam API will be RESTful, and built using python/tornado. The initial implementation will focus on "modules" speaking to each other. The initial expected modules/components are:

- storage server
- intake service (cert authority + upload)
- API service (tornado/python + couchdb REST calls with JSON returns)
- Phone module
- Web admin front-end (sammy, custom javascript, etc.)

Modules wishing to PUT/GET using the API must have a registered certificate with the InformaCam Server intake service in order to be granted access. This initial implemenatation will utilized this as its authorization mechanism during this initial implementation, instead trying to develop out a public-facing API that could conceivably require authorization approaches like OAuth, etc.

The web admin front-end will be as divorced from python as feasible, removing the majority of dependencies (e.g., avoiding python templates, etc.).

Get Object Record(s)¶

Path	Method	Description
/v1/derivative	GET	Get a media object's derivative record(s) by id

id parameter must be provided or will return as bad request.

Parameters¶

Name	Data Type	Required/Optional	Description	Use
id	string	required	unique id(s) used to identify a media object derivative record within InformaCam system's database	By default (when no additional parameters are added) an array for each of the objects is returned that includes the following: _id, alias, media type, time record was created, save location, submitted by, derivative thumbnail. To have additional metadata returned additional parameters must be supplied
sort	string	Optional	sort order of media records returned	Sort by (default date media is created): * dateSubmitted * dateCreated (date record created) * submitter
not_truncated	boolean	optional	if true return full derivative record
geneology	boolean	optional	if set to true, full geneology information will be returned	metadata returned: device id, ownership type, datetime media created on, datetime submitted, about the device, and device integrity
description	boolean	optional	if true returns custom categorical metadata added on server side	data returned is dependent on custom metadata implemented by organization (e.g., categorization, description,
form	boolean	optional	if true returns form data submitted through mobile device	dependent on implementation
annotations	boolean	optional	if true returns annotation data within the J3M
locations	boolean	optional	if true returns locations array (multiple lat/long locations recorded with J3M at time media is being recorded)
keywords	boolean	optional	if true returns array of keywords
region_bounds	boolean	optional	if true returns array of region bounds

Example
/v1/derivative?id=1,2,3&truncated=false&sort=dateCreated

Returned

Truncated example {

}

Full Example {

}

Search Object Records¶

Path	Method	Description
/v1/search	GET	Search media records

Records returned in a search will always be truncated, and will include the following: _id, alias, media type, time record was created, save location, submitted by, derivative thumbnail. Additional parameters will be provided dependent on the parameters requested.

At least one of the following parameters (except limit) but be supplied or will return bad request.

Parameters¶

Name	Data Type	Required/Optional	Description	Use
limit	int	optional	identify number of records to return
sort	string	Optional	sort the order of media records returned	Sort by (default is relevancy rating): * relevancy * dateSubmitted * dateCreated (date record created) * submitter
term	string	optional	keyword search object records
dateCreated	timestamp (?)	optional	search by date media was created
dateSubmitted	timestamp (?)	optional	search by date media was submitted
type	string	optional	search by media type	options: image, media
location	array	optional	search for objects within a geographical bounds	array should be formed similar to {"lat":0, "lng": 0, "radius": 5, "measure": "km"}. Measure can be kilometers (km) or miles (ml); default is km. radius can be decimal, default is 1. lat, lng should be down to (?); lat,long must be provided
custom	array	optional	search for objects using custom metadata fields	array passed should contain each custom term, followed by string of search query. E.g., custom={"ethnicity":"french", "status":"needs review"}

Example
/v1/search?term=my+dog&type=image

Returned

{

}

Submit media¶

TBD. Flesh out w/ Harlo better

Submit/Create New Record¶

Path	Method	Description
/v1/derivative	POST	Create a new derivative record when a media file is submitted/accepted to repository

Parameters¶

Name	Data Type	Required/Optional	Description	Use
j3m	json	required	decrypted j3m metadata (as a JSON object) is used to create a derivative record of a submitted media file	stringify json object before passing

Example
/v1/derivative?j3m=stringJSONhere

Update Existing Record¶

Path	Method	Description
/v1/updateRecord/[derivative id here]	PUT	Update metadata fields for an existing derivative record

Parameters¶

Name	Data Type	Required/Optional	Description	Use
id	alphanumeric	required	unique id used to identify a derivative record within the InformaCam system's database; the geocouch document id	ID should be appended to the URL as the final locator in the path
description	string	optional	add/update a description to the record of a submitted media file	this does not effect the original J3M submitted, only the derivative record created for the admin view
alias	string	optional	add/update a title to the record of a submitted media file
tier	string	optional	add / update a tier of a record of a submitted media file	IBA specific
status	string	optional	add / update a status of a record of a submitted media file to reflect that it has been review/approved by repository staff members	IBA requested; also helps meet ISO standard for trusted digital repositories
custom	json	optional	add custom field and corresponding value to a derivative record within the InformaCam system's database	pass stringified json array in the following format, to identify the key and value to add: {'key here': 'value here'}

Example
/v1/updateRecord/12345a2345?alias=this+is+a+new+title+for+this+record