|
API Description: Common arguments and response elements
Each response is built from several common blocks. Some of these blocks
depend on the specific collection you request (for instance price
history block for books), some are common.
What blocks are included in the response is defined by the content of
'results' variable. It contains a comma-separated list of block names.
Here is a list of common block names, along with examples of what they
produce:
- args - asks the server to echo back the arguments
it got. The server will only show arguments with recognized names, you
can use this argument to see if you server actually got the arguments
you send it.
Request example:
http://isbndb.com/api/books.xml?access_key=12345678&
results=args&index1=keywords&value1=lord+of+the+flies&foo=bar
Response example:
<?xml version="1.0" encoding="UTF-8"?>
<ISBNdb server_time="2005-02-25T23:03:41">
<Args>
<Arg name="access_key" value="12345678"/>
<Arg name="results" value="args"/>
<Arg name="index1" value="keywords"/>
<Arg name="value1" value="lord of the flies"/>
</Args>
<BookList total_results="7" page_size="10" page_number="1" shown_results="7">
...
</BookList>
</ISBNdb>
- keystats - statistics about the key you are
using. This includes how many times the key was used today, how many
time the access was granted, etc. The key itself if echoed back in
normalized way.
Request example:
http://isbndb.com/api/books.xml?access_key=C000lkey&
results=keystats&index1=isbn&value1=1231231231
Response example:
<?xml version="1.0" encoding="UTF-8"?>
<ISBNdb server_time="2005-02-25T23:03:41">
<KeyStats access_key="COOOLKEY" granted="4" requests="5" limit="50"/>
<BookList total_results="1" page_size="10" page_number="1" shown_results="1">
...
</BookList>
</ISBNdb>
See the next chapter for collection specific 'results' block names.
Results Pagination
For many types of requests it is possible to get a large number of
matched results -- for instance if you do a textual search using a
popular keyword. In such cases the response will include only a portion
of the total results set, a page. You can use 'page_number' argument to
scan through the entire results set if needed.
Here is an example response indicating that not all results are shown:
<?xml version="1.0" encoding="UTF-8"?>
<ISBNdb server_time="2005-02-25T23:03:41">
<BookList total_results="672" page_size="10" page_number="1" shown_results="10">
...
</BookList>
</ISBNdb>
You can see that your requests produced 672 total results, out of which
you see the first 10. If you need to see the very last page in this
example you would set page_number=68 argument in your query:
http://isbndb.com/api/books.xml?access_key=Z&page_number=68&index1=full&value1=sherlock
Results:
<?xml version="1.0" encoding="UTF-8"?>
<ISBNdb server_time="2005-02-25T23:03:41">
<BookList total_results="672" page_size="10" page_number="68" shown_results="2">
...
</BookList>
</ISBNdb>
Pages are counted from 1, the default value if there is no page_number
argument is also 1. Page size is always 10, there is currently no way to
request a different page size.
|
