DDBRest
The Deutsche Digitale Bibliothek is a database that provides free access to a huge amount of cultural and scientific datasets like books, archives, images, music or movies. With an API it makes this data available to many developers across several platforms, except JavaScript!
The DDBRest library binds all API interfaces in little handy methods and enables an easy access to all kinds of these data structures in Node.js and for the browser. It gives web-developers an easy start to use the DDB for their web-applications. It is cross-browser tested and AMD ready, so you can use it as module in your RequireJS or CommonJS application.
Install
Either download from GitHub or use NPM.
$ npm install ddbrest
or Bower
$ bower install ddbrest
Getting started
To get access to the DDB you have to register a user account on the website of the Deutsche Digitale Bibliothek. The access to the API is protected by an oAuth 1.0a protocol. Once you are registered you will receive an access token that grants you access it.
This library is an simple wrapper for the DDB API. It provides access to all of its interfaces and uses the Q promise implementation to easy chain multiple requests.
Setup
First, include the library and create a new instance of it by using your API token:
Or in Node.js environment:
var DDBRest = ;var api = '<access_token>';
Or used as AMD module in RequireJS:
;
Usage
The DDB API provides five general methods to access all kinds of different date structures. They are mapped to the
DDBRest instance and return data in application/json
format.
#
Searchapi.search([String] identifier)
The method search is providing an interface to the search engine of the DDB. You can specify your search by using
one of the following facets: affiliate
, place
, role
, keywords
, language
, type
, sector
, time
,
provider
, license
, licenseGroup
. Each of these facets are function which you can chain together. At the
end you fire the request by calling the get
command. Here are some examples:
api language'latin' ; api
Note: the request only gets fired if you call the get
method. It returns a promise object you can use to chain
more request after each other. You can pass the following parameters to restrict or order the searchresult:
- offset
Number
( default: 0 )
This is the number of the first entry of the result. - rows
Number
This is the count of result entries to be shown in total. - sort
String
( default: 'random_' )
Defines the sorting order, which can be one of the following values. It requires the query parameter, otherwise the sort is always random_. [ALPHA_ASC
,ALPHA_DESC
,RANDOM_<seed>
,RELEVANCE
] - minDocs
Number
The amount of documents a facet must exceed to be included in the result set. - facet.limit
Number
Limits the number of values of a facet to the given amount.
If you don't have a certain facet in your mind you can always request a list of facet suggestion. The count
attribute
tells you how many documents you'ld find when using this facet.
ddbrest;
#
Binaryapi.binary([String] identifier, [String] filepath)
The method binary returns the content of a binary file of an item for a given item-ID. This method provides response data as application/octet-stream. A binary file at DDB can be a picture, a tumbnail of a picture, a video clip, an audio file etc.
get()
Returns the raw binary data of requested file.
api
getPath()
Get url of file
api
toFile()
Download file to your file system (only Node.js environment).
api;
#
institutionsapi.institutions([String] sector)
The method institutions returns a list of institutions of specific sector types which are registered at the DDB.
get()
api// orapi
sectors
#
The method sectors returns the list of available institution sectors at the DDB.
api// orapi
#
itemsapi.items([String] identifier)
aip
#
The method aip returns the Archive Information Package (AIP) of an item for a given item-ID. An AIP contains all available information of an item including a persistent identifier. This is the only method that returns with an XML response.
api
binary
#
The method binaries returns a list of binary data files related to an item for a given item-ID. Binary data can be accessed with the binary method.
api
children
#
The method children returns metadata of these items which are related to the inquired item and which are one level deeper (child item) in the hierarchy than the inquired item. The child items will be sorted according to the position field of the hierarchy nodes. If the position is the same the label will be used for sorting. The provided metadata can be empty if the item does not have any child items.
api
edm
#
The method edm returns the Europeana Data Model (DDB profile) of an item for a given item-ID.
api
indexingProfile
#
The method indexing-profile returns the profile of an item for a given item-ID, which was used for the indexing process.
api
parents
#
The method parents returns item-IDs of these items which are related to the inquired item and which are one or more levels higher (parent, grandparent ... item) in the hierarchy than the inquired item. This means that all parent items up to the root item will be provided.
api
source
#
The method source returns the initial XML metadata of an item for a given item-ID. The format can be one of the accepted input data formats (e.g. MARCXML, METS/MODS, LIDO, Dublin Core).
apisource
view
#
The method view returns the view of an item for a given item-ID. A view is the data set a frontend page at DDB is based on.
api
Chain Multiple Request
As already mentioned, DDBRest uses Q promises to provide a proper way to chain multiple requests. You can combine DDBRest with the Q library to use the full power of promisses.
var Q = ; Qall api // request #1 api // request #2 api // request #3 { console; // outputs response of request #1 console; // outputs response of request #2 console; // outputs response of request #3};
With this technique you can also fire requests with values you've got from previous requests:
ddbrest;
Contributing
Please fork, add specs, and send pull requests! In lieu of a formal styleguide, take care to maintain the existing coding style.
Release History
- 2014-07-05 v0.1.0 first release
- 2014-07-06 v0.2.0 improved some implementations of first version, version to be presented at Codingdavinci Hackathon final