User Tools

Site Tools


book

Table of Contents

REST-object book

The book-object represents the data associated with a single book. It resides under http://btsoep.appspot.com/rest.

The object has support for different XML-formats in which data is returned; however, only one XML-format (ONIX) is currently available for public use.

For debugging purposes, the flag resultSetType may be used to return the raw data of a book in our database. Any other value for resultSetType (or none specified) yields ONIX output.

The path to the object is book/[recordreference], where recordreference represents a unique identifier. In general, the recordreference is equal to the ISBN13 / EAN of the book, although books that lack such an identifier may be assigned an internal reference.

Images: the book object includes images when it returns ONIX. Images are returned as URLs using the MediaFile composite. For example:

    <MediaFile>
      <MediaFileTypeCode>25</MediaFileTypeCode>
      <MediaFileLinkTypeCode>01</MediaFileLinkTypeCode>
 <MediaFileLink>http://lh6.ggpht.com/Dcgm4VGPRz5vtwOG78VncWTicg4iv8MKaJc5NBlOYsvA9Lt3_uBQq4iHWNFs9rFri5Xrh8Od_MWVmOw</MediaFileLink>
    </MediaFile>

We currently store images for fronts and backs of book covers. When we include a link to an image, we always include a link to a thumbnail as well. The values for MediaFileTypeCode are taken from ONIX codelist 39 (issue 2.1, rev 3): 4 = front cover, 6 = front cover thumbnail, 24 = back cover, 26 = back cover thumbnail.

Methods

This object understands the methods GET and POST.

method
GET retrieves the object, ie. retrieves information about a book

Method GET

GET is used to retrieve the object, in various forms. To retrieve information from our database, use this method.

Query-syntax

The query may contain the following key/value-pairs:

key value interpretation
key1 (key2 .. key5) search key (see searching below)
value1 (value2 .. value5) search value (see searching below)
flags1 (flags2 .. flags5) search flags (see searching below)
format onix return data in ONIX-format (don't generate a DTD-declaration, this will change soon) default
onix-nodtd return data in ONIX-format, but don't generate a DTD-declaration (but DO generate a namespace declaration)
boeknl return data in boeknl-format not available for public use
limit number (1, 2, 100) limit the # of hits to LIMIT; maximum number is currently 1000 Applies to CB & Boektrust databases
offset number (1, 2, 100) skip the first OFFSET # of hits

1. 404, “No database with that name exists” - an object in a 3rd party database was specified (http://btsoep.appspot.com/rest/book/unknowndatabase/9789062623310) but that 3rd party database is not known to this REST-object.

Examples

1. http://btsoep.appspot.com/rest/book/9789062623310 - Represents data for book 9789062623310. Because no query-information was specified, the default values are used: the level of detail returned is basic, the format of the data returned will be onix.

2. http://btsoep.appspot.com/rest/book/9789062623310?detail=basic&format=onix - This query will yield an identical response to the previous one. The query is now fully specified, but the values used are the same as the default ones.

3. http://btsoep.appspot.com/rest/book/9789062623310?detail=commercial - Represents data for book 9789062623310. The query-specification will result in a higher level of detail; both basic and commercial data will be included. Because no format was specified, the default format (ONIX) will be used to represent the data.

4. http://btsoep.appspot.com/rest/book/cb/978904470127 - Represents data for book 978904470127 from database cb. Because no query-information was specified, the default values are used: the level of detail returned is basic, the format of the data returned will be onix.

5. http://btsoep.appspot.com/rest/book/btnew/search?key1=recent&value1=30&flags1=0 - Returns a set of record that have been changed or inserted in the database since 30 days ago.

6. http://btsoep.appspot.com/rest/book/btnew/search?key1=title&value1=p&limit=9&offset=1 - Returns a set of 9 records with a 'p' in the title, start with the second record (= record #1, records numbered starting with 0).

7. http://btsoep.appspot.com/rest/book/btnew/search?key1=recent&value1=518400&limit=400&offset=0 - Returns a set of 100 records that have been changed in the last year (12 months * 30 days * 24 hours * 60 minutes = 518400).

8. http://btsoep.appspot.com/rest/book/978906262331?format=onix-nodtd - returns an ONIX-record that can be validated with a schema. For example, test with: curl “http://btsoep.appspot.com/rest/book/978906262331?format=onix-nodtd” |xmllint –format - | xmllint –schema ONIX_BookProduct_Release2.1_reference.xsd - .

DTD declaration

Some Windows-specific XML-processors add a delay for ONIX-records with fully specified external DTD-declarations. To facilitate processing with such processors, the ONIX-record can be generated without a DTD-declaration, through the format-flag.

Examples:

1. http://btsoep.appspot.com/rest/book/9789062623310 and http://btsoep.appspot.com/rest/book/9789062623310?format=onix - generate an XML with a fully specified DTD-declaration:

<?xml version="1.0"?>
<!DOCTYPE ONIXMessage SYSTEM "http://www.editeur.org/onix/2.1/reference/onix-international.dtd">
<ONIXMessage>
<!-- generated at 2008/06/08 23:21:05; svn revision 556M -->

2. http://btsoep.appspot.com/rest/book/9789062623310?format=onix-nodtd - generate an XML without a fully specified DTD-declaration:

<?xml version="1.0"?>
<ONIXMessage>
<!-- generated at 2008/06/08 23:21:56; svn revision 556M -->

6/8/2008: the default behavior of generating a DTD-declaration will go into effect soon. Until then, ALL records will be returned WITHOUT a DTD-declaration.

Searching

The path to the object may end in the generic word 'search'. In that case, the query string is used to give criteria to search for a SET of books. There may be different criteria (currently up to two) which may be used to limit the set. If there are 2 or more criteria, they are combined using logical AND.

CLOUD: the path to be used is ''http://btsoep.appspot.com/rest/search'' instead of ''http://btsoep.appspot.com/rest/book/*/search''. 

The criteria are given as a key/value pair, with optional flags if a key requires further detail. The current keys are:

key (string) value (string) flags (integer) example
title string ignored http://btsoep.appspot.com/rest/book/cb/search?key1=title&value1=papa&flags=0 searches for books which have 'papa' in their title
cloud: http://btsoep.appspot.com/rest/search?key1=title&value1=papa&flags=0 searches for books which have 'papa' in their title
recordreference string ignored http://btsoep.appspot.com/rest/book/cb/search?key1=recordreference&value1=978902574028&flags=0 searches for books with recordreference 978902574028 (recordreference only returns results for COMPLETE matches)
cloud: http://btsoep.appspot.com/rest/search?key1=recordreference&value1=978902574028&flags=0 searches for books with recordreference 978902574028 (recordreference only returns results for COMPLETE matches)
partialrecordreference (BROKEN) string ignored http://btsoep.appspot.com/rest/book/cb/search?key1=recordreference&value1=978906262&flags=0 searches for books with partial recordreference
contributor string role http://btsoep.appspot.com/rest/book/cb?key1=contributor&value1=papa&flags1=1 searches for authors (role = 1) which have 'papa' in their name
cloud: http://btsoep.appspot.com/rest/search?key1=contributor&value1=papa&flags1=1 searches for authors (role = 1) which have 'papa' in their name
geo string ignored http://btsoep.appspot.com/rest/book/btnew/search?key1=geo&value1=Weesp&flags1=0 searches for books about Weesp
nur string ignored http://btsoep.appspot.com/rest/book/btnew/search?key1=nur&value1=521&flags1=0 searches for books with NUR code 521
images 'required' ignored special key to limit result sets to only contain books with images
available 'required' ignored special key to limit result sets to only contain available (definition?) books
imprint string ignored http://btsoep.appspot.com/rest/book/btnew/search?key1=imprint&value1=Heureka&flags1=0 searches for books with imprint (=publisher name) Heureka
recent string ignored http://btsoep.appspot.com/rest/book/btnew/search?key1=recent&value1=1440&flags1=0 searches for books that have changed in the last 1 day (=1440 minutes)
roles

If the key is 'contributor', a role should be specified in 'flags'. The role is a number, and it is easily converted to and from an ONIX-defined role using the following algorithm:

When the ONIX-role is any …

  1. A-role, just use the number without the A (ex. A01 = 01).
  2. B-role, add the number without the B to 100 (ex. B01 = 01 + 100 = 101)
  3. C-role, add the number without the C to 200 (ex. C01 = 01 + 200 = 201)
  4. etc.
recency

If the key is 'recent', a number of minutes should be specified as the value. The result will be the books for which data has changed in the past VALUE minutes. If the value is unspecified or a non-integer value, the default current time is used instead of the value, which by default will result in an empty resultset (ie. error 404).

NUR

Nur code searching is possible for books. The value of 'value' can be either:

  • a 3-digit number, like “110”.
  • a range, like “110-120”. This must be the exact format: (digit)(digit)(digit)-(digit)(digit)(digit).

If the value has an invalid format, the REST-query returns an error string like 'An error occurred while connecting to the database, process ID 60688'. Valid values are '100-200', '001', '099', '341'. Invalid values are '1', '99', 'abcde', etc.

Sorting

The result set is sorted in DESCENDING order, based on the timestamp of the last modification of the record. The most recently changed record is returned first.

book.txt · Last modified: 2019/07/18 12:40 (external edit)