LUNA API Documentation
- amiller (Unlicensed)
- Luna
- dwong
There are two API's available:
LUNA Viewer API provides you with a convenient way to incorporate images from the LUNA Viewer into other web resources, like a website, wiki, blog, etc.
Record Data API allows for read, add, update and delete the record data contained within the LUNA Library.
On this page:
LUNA Viewer API
A JavaScript request and response API used to deliver search results from the LUNA Viewer.
Let’s say you have an exhibition you’d like to highlight on your website and the images reside in the LUNA Viewer, you can select this subset of images from the LUNA Viewer and promote them on your site. When a user clicks on one of the images they are taken to the LUNA Viewer. This LUNA Viewer API is a great way to bring your users into LUNA via your other web resources, primarily for images but will also support data. Example from the David Rumsey Historical Map Collection:
Searching
Example URL
Parameter | Description | Example |
q | The query to run. Specifying no query is the same as "view all." Query syntax is the same as is used by LUNA. For fielded search, use the advanced search as a template. | q=test or q=Pub_Title=ohio |
lc | Limit by collection. Luna collection IDs (Institution ID + "~" + Collection ID + "~" + Unique Collection ID), separated by comma. | lc=RUMSEY~8~1 or lc=RUMSEY~8~1,LUNA~1~1 |
sort | Up to 4 Luna fields separated by comma. | sort=Pub_List_No_InitialSort, Pub_Date,Pub_List_No, Series_No |
mgid | Media Group ID -- use this to specify the ID # for a group | mgid=25 |
random | Whether to randomly sort the resultset. true -- completely randomizes the order of the result set false (default) -- uses the specified sort | random=true |
os | Offset in result set. Used for paging. Default is 0. | os=25 |
bs | Batch Size (# of results to return). Default is 10. | bs=25 |
callback | Javascript callback. When the JSON data is returned, pass the data to the following function. | callback=myFunction <script> function myFunction(nodes) { var lst = nodes['data']; if (lst == undefined) lst = nodes; for (var i=0;i < lst.length;i++) { ... } } |
mid | Getting data for a specific record. Sometimes you just want data for one record without doing a search for it. Use the LUNA ID for the record (everything after /detail/). | mid=RUMSEY~8~1~520~60062 |
fullData | false by default. Setting this to true will include more data from the LUNA server instead of just the thumbnail images.
This must be used with individual records or an offset < 5. | fullData=true |
Results Structure
Metadata:
Note : this section is only included when the callback parameter is used.
The meta object is returned at the beginning of the response and contains basic information about the request including: total # of results, collections searched, info about the collections. A textual description of the search, and the offset.
Data:
The data array contains one object for each result. The values included are:
identity - the LUNA ID
mediaType - IMAGE, etc
urlSize0 - size 0 image URL
urlSize1 - size 1 image URL
urlSize2 - size 2 image URL
Additional values when fullData=true
displayName - the "title" field as mapped in the LAS
summary field values (the data shown in a mouse-over on a LUNA result set)
preview field values (the thumbnail labels)
urlSize3 - size 3 image URL
urlSize4 - size 4 image URL
IIIF URLs
As of version 7.3.1 you can include IIIF URL's in the response.
Record Data API
Read, add, update and delete the record data contained within the LUNA Library.
This API uses OAuth to authenticate access to the LUNA Library. Once authorized the OAuth user can view, add, edit and delete Record data from the LUNA Library based on the privileges the OAuth user has been granted.
The LUNA Record Data API is about making the LUNA system sync with your external cataloging system, or data source. For example, if you are cataloging your records in Filemaker the Record Data API allows this data to sync with LUNA. So if you need to make edits to records you can continue to do so in Filemaker and these edits will also be updated in LUNA. Alternately if you want to edit records in LUNA the edits will also be updated in Filemaker.
Using OAuth with LUNA Library
What is OAuth?
We think Yahoo sums it up quite well. OAuth is an open, simple, and secure protocol that enables applications to authenticate users and interact with LUNA on their behalf. The end user's information is securely transferred without revealing the identity of the user. At Luna, we use OAuth to verify that an application trying to interact with the LUNA Library on your behalf is doing so only with the permissions you have granted it.
To learn more about OAuth 1.0, please visit:
http://oauth.net/core/1.0/
Getting Started
To get started, first obtain a key and shared consumer secret for the application by registering it with the LUNA Library (Change the domain name and port number for your server) :
http://www.example.com:8181/editor/e/developers/apps
On this page, you are presented with a list of applications currently registered under the username you are logged in as.
When you click on 'Create', you will be asked the following:
App Name - the name of the application that's going to be interacting with the LUNA Library.
Callback URL(optional) - the default URL to redirect an authorized user back to the application when a callback URL is not provided along with the original request.
App Description(optional) - A short description of this application
On the next page, two values will be generated:
Key - a unique identifier of this application registered with the LUNA Library
Token secret - a shared secret which the application will use to compute signatures.
Keep in mind that the application will have access to the same set of collections as the user account under which this application is registered.
Making OAuth Requests
The URLs for requesting tokens and authorization are as follows:
http:// + hostname + port_number + /editor/e/oauth/request_token
http:// + hostname + port_number + /editor/e/oauth/authorize
http:// + hostname + port_number + /editor/e/oauth/access_token
References:
https://www.dropbox.com/developers/core/docs#request-token
http://www.flickr.com/services/api/auth.oauth.html
Using the Record data API
/collections/{collectionId} (GET)
DESCRIPTION | Gets a list of “items” from the collection. An “item” can contain only media, only record, or both media and record if linked together. Use Get-Record request to retrieve full record data. Paging is possible with parameters. |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
PARAMETERS | os The result offset. Server will return items starting from this number. |
pgs The size of the results return. Default is 50. | |
METHOD | GET |
ERROR | 400 General Error |
RETURNS |
|
/collections/{collectionId} (POST)
Description | Uploads new record(s) to the specified collection. |
URL Structure | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier of the collection | |
METHOD | POST |
REQUEST BODY | (required) The record(s) being uploaded in XML. The entire POST body will be treated as XML. Example: <recordList> <record> <field_name1>...</field_name1> <field_group_name1> <field_name2>...</field_name2> </field_group_name1> </record> ... </recordList> |
ERROR | 400 General error from processing uploaded records. |
/collections/{collectionId}/records/{recordId} (PUT)
DESCRIPTION | Update an existing record |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/records/<Record ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
METHOD | PUT |
REQUEST BODY | (required) The record being updated in XML. Must contain exactly 1 record. The entire POST body will be treated as XML. Example: <recordList> <record> <field_name1>...</field_name1> <field_group_name1> <field_name2>...</field_name2> </field_group_name1> </record> </recordList> |
ERROR | 400 Invalid Record ID or content body contains more than 1 record |
404 Unable to find record with the provided record ID |
/collections/{collectionId}/records/{recordId} (DELETE)
DESCRIPTION | Delete an existing record |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/records/<Record ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
METHOD | DELETE |
ERROR | 400 Invalid Record ID |
404 Unable to find record with the provided record ID |
/collections/{collectionId}/mappings/record/{recordId}/media/{mediaId} (POST)
DESCRIPTION | Create a mapping between a record and a media |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/mappings/record/<Record ID>/media/<Media ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
Media ID The unique identifier for the media | |
METHOD | POST |
ERROR | 400 Invalid Record ID or Media ID |
404 No record found with the given Record ID |
/collections/{collectionId}/mappings/record/{recordId}/media/{mediaId} (PUT)
DESCRIPTION | Update existing mappings with the record. Any existing media currently linked to the record will be unlinked and replaced by this mapping. |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/mappings/record/<Record ID>/media/<Media ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
Media ID The unique identifier for the media | |
METHOD | PUT |
ERROR | 400 Invalid Record ID or Media ID |
404 No record found with the given Record ID |
/collections/{collectionId}/mappings/record/{recordId}/media/{mediaId} (DELETE)
DESCRIPTION | Remove this mapping from the record. Other media that is linked to the record will be left untouched. |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/mappings/record/<Record ID>/media/<Media ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
Media ID The unique identifier for the media | |
METHOD | DELETE |
ERROR | 400 Invalid Record ID or Media ID |
404 No record found with the given Record ID |
/collections/{collectionId}/mappings/record/{recordId}/batch/{batchId}/filename/{filename} (POST)
DESCRIPTION | Create a mapping between a record and a media. Instead of providing Media ID, Batch ID and Filename is used in this request. |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/mappings/record/<Record ID>/batch/<Batch ID>/filename/<Filename> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
Batch ID The unique identifier for batch to which the media is uploaded | |
Filename The name of the media file. | |
METHOD | POST |
ERROR | 400 Invalid Record ID or Batch ID or Filename |
404 No record found with the given Record ID |
/collections/{collectionId}/mappings/record/{recordId}/batch/{batchId}/filename/{filename} (PUT)
DESCRIPTION | Update existing mappings with the record. Any existing media currently linked to the record will be unlinked and replaced by this mapping. Instead of providing Media ID, Batch ID and Filename is used in this request. |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/mappings/record/<Record ID>/batch/<Batch ID>/filename/<Filename> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
Batch ID The unique identifier for batch to which the media is uploaded | |
Filename The name of the media file. | |
METHOD | PUT |
ERROR | 400 Invalid Record ID or Batch ID or Filename |
404 No record found with the given Record ID |
/collections/{collectionId}/mappings/record/{recordId}/batch/{batchId}/filename/{filename} (DELETE)
DESCRIPTION | Remove this mapping from the record. Other media that is linked to the record will be left untouched. Instead of providing Media ID, Batch ID and Filename is used in this request. |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/mappings/record/<Record ID>/batch/<Batch ID>/filename/<Filename> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
Batch ID The unique identifier for batch to which the media is uploaded | |
Filename The name of the media file. | |
METHOD | DELETE |
ERROR | 400 Invalid Record ID or Batch ID or Filename |
404 No record found with the given Record ID |
/collections/{collectionId}/records/{recordId} (GET)
DESCRIPTION | Gets full data for a record |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/records/<Record ID> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Record ID The unique identifier for the record | |
PARAMETER | rawMode DEFAULT 0. Set to 1 to return records in the same XML format as it is stored. |
METHOD | GET |
RETURNS | |
ERROR | 400 Invalid Record ID |
/collections/{collectionId}/records (GET)
DESCRIPTION | Gets full data for a record |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/records |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
PARAMETER | search_field (required) The name of the field to perform the search |
search_value (required) The value to find in the specified field | |
os The result offset. Server will return items starting from this number. | |
pgs The size of the results return. Default is 50. | |
METHOD | GET |
RETURNS | Sample XML Response: <librarySearchResult> |
ERROR | 400 Invalid search parameters |
/collections/{collectionId}/batch/{batchId}/filename/{filename} (GET)
DESCRIPTION | Get a media in a batch using filename |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/batch/<Batch ID>/filename/<Filename> |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
Batch ID The unique identifier for the batch where the media exists | |
Filename The name of the media file | |
METHOD | GET |
RETURNS | Sample XML Response: <librarySearchResult> |
ERROR | 400 Invalid batch ID or filename |
/collections/{collectionId}/entities (POST)
DESCRIPTION | Adds an entity(field group) to record(s) that match the given criteria |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/entities |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
PARAMETER | parent_field_name (required) The name of the field whose entity under which you are adding the new entity |
parent_field_value (required) The value of the field whose entity under which you are adding the new entity | |
search_field The name of the field to perform the search. Use this parameter to filter the number of records to update. | |
search_value The value of the field to perform the search. Use this parameter to filter the number of records to update. | |
METHOD | POST |
ERROR | 400 General Error |
| PHP EXAMPLE | To add a field group with name "Keywords" that contains a field called "Keyword" with value "painting": $data='<keywords><keyword>painting</keyword></keywords>';
$url = $_SESSION['server_address'] . "/editor/e/api/collections/" . $collection_id
. "/entities?parent_field_name=work_record_id&parent_field_value=0052891"
."&search_field=work_record_id&search_value=0052891";
$oauth->fetch($url, $data, OAUTH_HTTP_METHOD_POST, array('Content-Type' => 'text/plain'));
In this example, the "Keywords" field group is located at the top level with reference to the catalog template, "Work Record ID" is a unique identifier that is also not inside any field group. Therefore, Parent Field and Search Field and their values are the same. In the case of adding nesting field groups, they will differ. |
/collections/{collectionId}/entities (PUT)
DESCRIPTION | Updates an entity (field group) in record(s) that match the given criteria |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/entities |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
PARAMETER | search_entity_field (required) The name of the field within the entity that is being replaced. Use with search_entity_value to locate the target entity within the record. |
search_entity_value (required) The value of the field within the entity that is being replaced. Use with search_entity_field to locate the target entity within the record. | |
search_field The name of the field to perform the search. Use this parameter to filter the number of records to update. | |
search_value The value of the field to perform the search. Use this parameter to filter the number of records to update. | |
parent_field_name The name of the field in the parent of the entity that is being replaced. Use this with parent_field_value in case of repeating entities in a nested structure to uniquely identify the target entity. | |
parent_field_value The value of the field in the parent of the entity that is being replaced. Use this with parent_field_name in case of repeating entities in a nested structure to uniquely identify the target entity. | |
METHOD | PUT |
ERROR | 400 General Error |
/collections/{collectionId}/entities (DELETE)
DESCRIPTION | Deletes an entity(field group) in record(s) that match the given criteria |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/collections/<Collection ID>/entities |
LUNA Library Base URL The server address and port number to the Luna installation | |
Collection ID The unique identifier for the collection | |
PARAMETER | parent_field_name The name of the field whose entity under which you are deleting the entity |
parent_field_value The value of the field whose entity under which you are deleting the entity | |
search_field The name of the field to perform the search. Use this parameter to filter the number of records to update. | |
search_value The value of the field to perform the search. Use this parameter to filter the number of records to update. | |
search_entity_field (required) | |
search_entity_value (required) | |
METHOD | DELETE |
ERROR | 400 General Error |
/ping
DESCRIPTION | Checks that the server is alive |
URL STRUCTURE | http://<LUNA Library Base URL>/editor/e/api/ping |
LUNA Library Base URL The server address and port number to the Luna installation | |
METHOD | GET |
ERROR | 400 General Error |