Created by Than Grove (May, 2014)
This module adapts code from Jack Kelly's Shared Shelf Media module extension into a Drupal API service to call Shared Shelf for data in JSON or XML format.
There are no dependencies for this module other than having an account on Shared Shelf. At present, only one account can be references per Drupal installation. After installing the module you will need to go to /admin/config/services/sharedshelf_api and enter in information about the Shared Shelf account to which this installation will be connected. By default, Admins can set Shared Shelf authorization data but this permission can be changed at /admin/people/permissions#module-sharedshelf_api
Once set up, the module will enable GET calls for information from the associated Shared Shelf account. No PUT account modifications are enabled at this time. The data format for the returned information is specified by the extension: '.json' returns JSON and '.xml' returns XML. The format of the JSON or XML is specific to Shared Shelf. The following is a list of calls and their description:
| API Call | Description |
|---|---|
|
/sharedshelf/api/assets/{asset ID #}.json /sharedshelf/api/assets/{asset ID #}.xml e.g., /sharedshelf/api/assets/2652868 |
Returns information about a single asset |
|
/sharedshelf/api/assets/{asset ID #}/representation (or) /sharedshelf/api/assets/representation/size/{0 through 4} e.g., /sharedshelf/api/assets/2652868/represetation (or) /sharedshelf/api/assets/2652868/represetation/size/3 |
This call redirects to the actual Shared Shelf URL for images. If no size is specificed then the full-sized image is given. Otherwise the numbers represent the following sizes: 0 => 64px wide, 1 => 128px, 2 => 256px, 3 => 512px, 4 => 1024px. |
|
/sharedshelf/api/projects.json /sharedshelf/api/projects.xml |
This returns a list of projects associated with the account. |
|
/sharedshelf/api/projects/{project ID #}/assets.json /sharedshelf/api/projects/{project ID #}/assets.xml e.g., /sharedshelf/api/projects/534/assets.xml |
Returns a list of assets for project number with the ID number of #. |
|
/sharedshelf/api/projects/###/assets/filter/{field_name}/{field_value}.json /sharedshelf/api/projects/###/assets/filter/{field_name}/{field_value}.xml i.e., /sharedshelf/api/projects/534/assets/filter/fd_24809_lookup.links.source_id/1300.json |
Returns assets from project ### which have a {field_name} whose value is {field_value}. fd_24809_lookup.links.source_id = Kmaps Subject (for Shanti Shared Shelf) fd_24803_lookup.links.source_id = Kmaps Places Note: Filter field variable type is hard-coded to "string". The code will have to be updated to accomodate other variable types, if needed. |
The format of the returned is quite elaborated and cannot be fully described here. The best way to understand the return data for processing it to look at a few examples once the module is installed. However, a few comments can be made. In XML the top-level or root element is always <results>; in JSON this is represented simply as curly brackets. All returned result sets have the following fields:
| Field Name | Description |
|---|---|
| total | The total number of results returned |
| assets (or items) | An array of returned assets or items (for project list). Each asset or item is marked up according to Shared Shelf's unique and somewhat complex markup scheme. |
| success | A boolean set to true if the call was successful |
| api_host | The host server url for the account, usually http://catalog.sharedshelf.artstor.org |
| api_path | The service path of the call without the extension, e.g. /projects/534/assets |