====== 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: 25 01 http://lh6.ggpht.com/Dcgm4VGPRz5vtwOG78VncWTicg4iv8MKaJc5NBlOYsvA9Lt3_uBQq4iHWNFs9rFri5Xrh8Od_MWVmOw 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 ^ effect | 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 | | === Return codes === 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: 2. ''http://btsoep.appspot.com/rest/book/9789062623310?format=onix-nodtd'' - generate an XML without a fully specified DTD-declaration: 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 ... - A-role, just use the number without the A (ex. A01 = 01). - B-role, add the number without the B to 100 (ex. B01 = 01 + 100 = 101) - C-role, add the number without the C to 200 (ex. C01 = 01 + 200 = 201) - 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.