Public API inputs and outputs

We discussed at the Paris meeting the range of parameters that we

thought that an API might need to handle to perform the sort of
(public-facing) tasks we envisaged. We didn't actually talk about
output, except in regard to the ability to specify return fields, but I
think that this is actually much the simpler part to work out. I've
reworked our discussion, added a few bits of my own (including the
UGC bit), and split it into sections relating to general parameters,
filters for collections queries, and UGC. No doubt lots more clarification
and revision are needed and I'm pretty unclear on some bits myself,
but it's something!

Input parameters

The “profile” includes various elements defining the operation in terms

of function, languages, values and format of returned data etc.
Collections data requests will be required for some functions, and
consist of various filters. The third table relates to operations on user
generated content, including adding, editing and getting (by user or
group). We may decide that some operations are only open to specific
users or categories of user; for example, accessing UGC of some
categories might only be possible for the owner of that UGC (via their
associate API key) or the owner of the collections related to that UGC.
TBC!

Query profile (data access and data addition/editing functions)

Parameter Access or Example values, notes

edit

Function A search, compare, translate, add,

[required] update
Return format A, E DC-XML, RSS, geoRSS, CDWALite,
JSON, CSV. This might instead be
[required]
implicit in the target URL.

Return fields A Array of field names, but a default

set would perhaps include GUID,
title, thumbnail, short description,
owner, owner type, media. Might
also provide shortcuts to preset
field groups. Will vary according to
target entities

Search data A Formal metadata; all data; expert

and user tags; user tags only;
“expert” tags only; specific
user/expert/group tags.

Expanded terms A True, false [use/don’t use thesauri

etc.]

Requesting A, E EN, FR etc.

language

Return A, E As above. If only one is present

language presume the same.

Key [required] A, E API user key

User ID A, E For the end user. Required for

[required for accessing/modifying data attached
some to specific users or groups.
operations] Presumably we need to
authenticate and authorise in some
way, too, for some operations.

Rights/licence A, E Perhaps multi-value, specifying

 rights/licensing parameters. Likely
to be more complex than one field!

Collection data filters (access only)

Parameter Example values, notes

Target entities Objects, people, places, subjects [if we are

enabling anything more than objects]

Keyword Tricycle, ww2, treaty, Anne Briggs, documentary

[multi-field search].

GUID Unique ID for an entity

Set ID ID for a set of entities, which may require the

appropriate key, depending upon privacy settings
for that set.

Structured Name of object, person or place. If these use

data: name different fields, then the right one should be
inferred from the target entity.

Examples: photograph; sunflowers; Forlì (or Forli);

Max Brod (or M Brod); Rockall

Structured 14 July 1792; 19th century. “Older than 1850”

data: date might be expressed as: “-20000000 – 1850”;
[point, range, “Younger than” as: “1850-2050”; uncertainty like
older, younger] “1850 +- 5” as a range: “1845-1855”, though this
isn’t perfect

Structured For returning objects, people and places

data: related
person

Structured For returning objects, people and places. See also

data: related “geographical” below.
place

Subject

Original Of object, principally, for documents (if this data

language is well expressed)

Originating Good structured data, ideally (we may require an

institution ID), but we could permit a string search across
the relevant field.

Originating For searching by current location

institution
country

Originating Museum, library, archive, A/V archive

institution type

Location Including sub-parameters for grid reference,

coordinates, place name, and the location of
concern (e.g. place of creation, place of
publication, location of subject matter)

Sorting Keyword occurrence, date precision, location,

location relative to user, institution type – perhaps
sorting partly inferred from the fields used in
search, but if these are mixed e.g. date and place
plus keyword, need to sort on one before the
other.

Media text, audio, image, video or more specifically PDF,

WAV, MPEG etc.

Format [item Map, book, video perhaps. Is this data held in a

type] structured way, and is it distinct from the media
metadata?
UGC operations (add, edit, view)

These operations will need user ID (or group ID) plus authentication
and authorisation for certain operations (but not for viewing public
data).

Parameter Access/edit Example values, notes

tag A, E For modifying tag i.e. deleting, or

viewing associated items

note A, E For modifying or viewing

UGC contributor A, E Perhaps multiple values, including

groups, so we can look for stuff with
a given tag but only when tagged
by a certain set of UGC contributors

UGC contributor A, E Content contributor vs. other user

type