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.

This object understands the methods GET and POST.

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

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

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.

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 - .

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.

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:

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.

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 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.

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.