| body |
## Read API
<script src="/static/js/json2.js" type="text/javascript"></script>
<script>
function query(request, response) {
request = JSON.stringify(request, null, " ").replace(/\//g, '\\/');
response = JSON.stringify(response, null, " ").replace(/\//g, '\\/'); // simplejson escapes /. DO samething here.
var a = $("<div>").append($("<pre>").append(request)).addClass("query").css("width", "400px");
var b = $("<div>").append($("<pre>").append(response)).addClass("response").css("width", "400px");
var tr = $("<tr>")
.append($("<td>").append(a).attr("valign", "top"))
.append($("<td>").append("⇒").attr("valign", "top").addClass("arrow"))
.append($("<td>").append(b).attr("valign", "top"));
var table = $("<table>").append(tr)
.attr("cellpadding", 0)
.attr("cellspacing", 0)
.attr("border", 0)
.css("width", "800px");
var div = $("<div>").append(table).css("margin-left", "100px");
document.write(div.parent().html());
}
</script>
Infogami provides an API to query the database for objects matching particular criteria or to `get` an object from the database. All the requests take input either as part of the URL or query string. You can try sample requests and practice building requests in the <a href="/api_sandbox">API sandbox</a>.
<p style="padding-left: 224px;">
<img src="/static/images/arrow.red.png" alt="arrow" /><a href="#querying">Querying for Objects (/things)</a><br />
<img src="/static/images/arrow.red.png" alt="arrow" /><a href="#getting">Getting an Object (/get)</a><br />
<img src="/static/images/arrow.red.png" alt="arrow" /><a href="#versions">Queries for Versions (/versions)</a><br />
<img src="/static/images/arrow.red.png" alt="arrow" /><a href="#search">Search queries (/search)</a><br />
</p>
The database structure, developed by the Open Library, is called <em>infogami</em>. Infogami stores a collection of objects, called "things". For example, on the Open Library site, each page, book, author, and user is a thing in the database. Each thing then has a series of arbitrary key-value pairs as properties. For example, a book thing may have the key "title" with the value "A Heartbreaking Work of Staggering Genius" and the key "genre" with the value "Memoir". Each collection of key-value pairs is stored as a version, along with the time it was saved and the person who saved it.
Because in infogami everything is an object, you can query for any object in infogami space, such as templates, editions, authors, or individual infogami fields in any page type. Each object has an object type. (<a href="/type">List of types.</a>) For example, there is `/type/edition` which represents all of the information about a book, and `type/edition/isbn_10` which is the property for the 10-character ISBN in the edition record.
<br clear="all" />
<a name="querying"></a>
### Querying for Objects (/things)
To find objects matching a particular query, send a GET request to <http://openlibrary.org/api/things> with `query` as parameter. In this documentation we use curl as a simple command line query client; any software that supports http `GET` can be used.
The `query` must use <a href="http://www.ietf.org/rfc/rfc4627.txt?number=4627">JSON</a> dictionary syntax.
This query searches for all editions with a particular ISBN value, and returns the keys of all matching records. Since there can be only one book with the any ISBN, the result contains only one key. (In practice unfortunately you will see publishers have reused an ISBN for otherwise unrelated works.)
<script>
var request = {
"type": "/type/edition",
"isbn_10": "0789312239",
};
var response = {
"status": "ok",
"result": [
"\/b\/OL3315616M"
]
};
query(request, response);
</script>
A curl request for the above, then, would read as follows:
<div class="query" style="width: 800px; margin-left: 100px;">
<pre>$ curl -G --data-urlencode 'query={"type":"\/type\/edition", "isbn_10":"0789312239"}' \
http://openlibrary.org/api/things</pre>
</div>
#### Pattern matching
The API supports querying for objects based of string matching.
Here is an example to get all object with key starting from `/about/`.
<script>
var request = {
"key~": "/about/*"
};
var response = {
"status": "ok",
"result": [
"\/about\/architecture",
"\/about\/banned",
"\/about\/calendar",
"\/about\/catalog",
"\/about\/contact",
"\/about\/faq",
"\/about\/help",
"\/about\/help\/libraries",
"\/about\/help\/oclc",
"\/about\/help\/upload",
"\/about\/infogami-dc",
"\/about\/jobs",
"\/about\/lib",
"\/about\/ol_info_sheet",
"\/about\/olmeeting2008",
"\/about\/oln",
"\/about\/pagelist",
"\/about\/people",
"\/about\/performance",
"\/about\/press",
"\/about\/publishers",
"\/about\/relnote",
"\/about\/sample_publisher_letter",
"\/about\/schema",
"\/about\/tech",
"\/about\/vision"
]
};
query(request, response);
</script>
Due to performance reasons, `*` is allowed only at the end of a string.
#### The Sort Directive
The `sort` directive can be used to tell Infogami to sort the results of a query before returning.
The following query gives the list of all documents sorted in the order of their keys.
<script>
var request = {
"type": "/type/doc",
"sort": "key"
};
var response = {
"status": "ok",
"result": [
"\/dev\/docs\/api",
"\/dev\/docs\/infogami",
"\/dev\/docs\/ui"
]
};
query(request, response);
</script>
By default sort operation returns the results in the ascending order. To reverse that order, prepend minus (`-`) to the value of `sort` directive.
<script>
var request = {
"type": "/type/doc",
"sort": "-key"
};
var response = {
"status": "ok",
"result": [
"\/dev\/docs\/ui",
"\/dev\/docs\/infogami",
"\/dev\/docs\/api"
]
};
query(request, response);
</script>
#### Limiting Queries
By default every results of every query are limited to 100 values. Alternate limit can be specified by using the `limit` directive.
Here is an example to get first 10 templates.
<script>
var request = {
"type": "/type/template",
"sort": "key",
"limit": 10
};
var response = {
"status": "ok",
"result": [
"/templates/advanced_search.tmpl",
"/templates/backlinks.tmpl",
"/templates/default_diff.tmpl",
"/templates/default_edit.tmpl",
"/templates/default_input.tmpl",
"/templates/default_ref.tmpl",
"/templates/default_repr.tmpl",
"/templates/default_view.tmpl",
"/templates/deleted.tmpl",
"/templates/diff.tmpl"
]
};
query(request, response);
</script>
The `offset` directive can be used to ask infogami to give results from a specific offset.
The following query gives the next 10 templates.
<script>
var request = {
"type": "/type/template",
"sort": "key",
"limit": 10,
"offset": 10
};
var response = {
"status": "ok",
"result": [
"\/templates\/editpage.tmpl",
"\/templates\/forgot_password.tmpl",
"\/templates\/fullsearch.tmpl",
"\/templates\/history.tmpl",
"\/templates\/i18n.tmpl",
"\/templates\/imageupload.tmpl",
"\/templates\/login.tmpl",
"\/templates\/login_preferences.tmpl",
"\/templates\/notfound.tmpl",
"\/templates\/password_mailer.tmpl"
]
};
query(request, response);
</script>
#### Expression AND in queries
All the keys in the query other than special directives (`sort`, `limit`, `offset`) are implicitly ANDed.
For example, the following query finds all objects having type as `/type/edition` and author as Mark Twain (`/a/OL18319A`).
<script>
var request = {
"type": "/type/edition",
"authors": "/a/OL18319A",
"sort": "key",
"limit": 5
};
var response = {
"status": "ok",
"result": [
"\/b\/OL1001932M",
"\/b\/OL1016757M",
"\/b\/OL1017798M",
"\/b\/OL1045540M",
"\/b\/OL105166M"
]
};
query(request, response)
</script>
<a name="getting"></a>
### Getting an Object (/get)
In Infogami, every object is identified by a unique key. In the example above, we queried the database on an ISBN and were returned the unique key for the edition that matches that ISBN. We can then retrieve the edition with a `get` command:
<div class="query" style="width: 800px; margin-left: 100px;">
<pre>$ curl http://openlibrary.org/api/get?key=/b/OL1001932M</pre>
</div>
This returns:
<div class="response" style="width: 800px; margin-left: 100px;">
<code class="normal">
{ "status": "ok", "result": { "subject_place": [ "Venice (Italy)"], "lc_classifications": [ "DG674.2 .S3 2005" ], "latest_revision": 1, "genres": [ "Juvenile literature."], "title": "This is Venice", "languages": [ { "key": "\/l\/eng" }], "subjects": [ "Venice (Italy) -- Description and travel -- Juvenile literature."], "publish_country": "nyu", "by_statement": "M. Sasek.","type": { "key": "\/type\/edition" }, "revision": 1, publishers": [ "Universe"], "last_modified": "2008-04-01T03:28:50.625462", "key": "\/b\/OL3315616M", "authors": [ { "key": "\/a\/OL1396639A" } ], "publish_places": [ "New York, NY" ], "pagination": "56 p. :", "lccn": [ "2004110229" ], "notes": "\"A children's classic\"--Cover.\nOriginally published: New York : Macmillan, 1961.", "number_of_pages": 56, "isbn_10": [ "0789312239" ], publish_date": "2005" }}
</code>
</div>
Because this string is hard to read, you may want to add the parameter "prettyprint=true" when you are testing your queries.
<div class="query" style="width: 800px; margin-left: 100px;">
<pre>$ curl http://openlibrary.org/api/get?key=/b/OL1001932M&prettyprint=true</pre>
</div>
This returns a more eye-readable version of the same string.
<div class="response" style="width: 800px; margin-left: 100px;">
<pre># response
{
"status": "ok",
"result": {
"subject_place":
"Venice (Italy)",
"lc_classifications":
"DG674.2 .S3 2005",
"latest_revision": 1,
"genres": [
"Juvenile literature."
],
"title": "This is Venice",
"languages": [
{
"key": "\/l\/eng"
}
],
"subjects": [
"Venice (Italy) -- Description and travel -- Juvenile literature."
],
"publish_country": "nyu",
"by_statement": "M. Sasek.",
"type": {
"key": "\/type\/edition"
},
"revision": 1,
"publishers": [
"Universe"
],
"last_modified": "2008-04-01T03:28:50.625462",
"key": "\/b\/OL3315616M",
"authors": [
{
"key": "\/a\/OL1396639A"
}
],
"publish_places": [
"New York, NY"
],
"pagination": "56 p. :",
"lccn": [
"2004110229"
],
"notes": "\"A children's classic\"--Cover.\nOriginally published: New York : Macmillan, 1961.",
"number_of_pages": 56,
"isbn_10": [
"0789312239"
],
"publish_date": "2005"
}
}</pre>
</div>
The following example gets the page `/pagelist` using the API.
<div class="query" style="width: 800px; margin-left: 100px;">
<pre> $ curl http://openlibrary.org/api/get?key=/pagelist?prettyprint=true
{
"status": "ok",
"result": {
"body": "{{PageList(\"\/\")}}",
"title": "Page List",
"last_modified": "2008-04-18T09:19:56.978194",
"latest_revision": 1,
"key": "\/pagelist",
"type": {"key": "\/type\/page"},
"revision": 1
}
}</pre>
</div>
Since the response is in JSON format, the Content-Type is set to `application/json`, which may not be displayed by the browsers as text. To enable that `text=true` must be passed in the query string.
<a name="versions"></a>
### Queries for Versions (/versions)
In Infogami, modification of every object creates a new version of that object.
To find versions matching a particular query, send a GET request to <http://openlibrary.org/api/versions> with `query` as parameter. The `query` must be a JSON dictionary, just like the things query. The `sort` and `limit` directives work similar to the things query.
For example the following query finds the most 10 versions of `/` object.
<div style="margin-left: 100px;">
<table cellpadding="0" cellspacing="0" border="0" style="width: 800px"><tr><td valign="top">
<div class="query">
<pre># Query
{
"key": "/",
"limit": 3,
"sort": "-created"
}</pre>
</div>
</td>
<td valign="top" class="arrow">⇒</td>
<td valign="top">
<div class="response">
<pre># Response
{
"status": "ok",
"result": [
{
"comment": "",
"created": "2008-04-18T15:40:04.279578",
"ip": "207.241.226.140",
"author": "\/user\/webchick",
"thing_id": 9875590,
"key": "\/",
"id": 9894268,
"machine_comment": null,
"revision": 14
},
{
"comment": "",
"created": "2008-04-18T15:39:30.588136",
"ip": "207.241.226.140",
"author": "\/user\/webchick",
"thing_id": 9875590,
"key": "\/",
"id": 9894267,
"machine_comment": null,
"revision": 13
},
{
"comment": "",
"created": "2008-04-16T00:18:32.743829",
"ip": "207.241.226.140",
"author": "\/user\/webchick",
"thing_id": 9875590,
"key": "\/",
"id": 9894257,
"machine_comment": null,
"revision": 12
}
]
}</pre>
</div>
</td></tr></table>
</div>
<a name="search"></a>
### Search queries (/search)
There is an incomplete search API as the final interface has not been decided. Only rudimentary search functions are supported for now. Development in progress is being discussed in the Open Library bug tracker at <a href="https://bugs.launchpad.net/openlibrary/+bug/236947">https://bugs.launchpad.net/openlibrary/+bug/236947</a>; interested parties are invited to post comments and requests in that tracker item.
A search API query is a JSON dictionary passed as the "q" http parameter. The dictionary just one meaningful entry, "query". The response is a json object containing a list of openlibrary id's. The optional argument "prettyprint" http parameter controls formatting of the response, as above. In the example below, the query is
<pre>
http://openlibrary.org/api/search?q={"query":"Felix Klein"}&prettyprint=true
</pre>
<div style="margin-left: 100px;">
<table cellpadding="0" cellspacing="0" border="0" style="width: 800px"><tr><td valign="top">
<div class="query">
<pre># Query
{
"query": "Felix Klein",
}</pre>
</div>
</td>
<td valign="top" class="arrow">⇒</td>
<td valign="top">
<div class="response">
<pre># Response
{
"status": "ok",
"result": [
"/b/OL1618362M",
"/b/OL3253308M",
"/b/OL2532653M",
"/b/OL2628261M",
"/b/OL5501881M",
"/b/OL1299055M",
"/b/OL2099784M",
"/b/OL2418293M",
"/b/OL3303109M",
"/b/OL4412463M",
"/b/OL5068782M",
"/b/OL5305191M",
"/b/OL5550601M",
"/b/OL5550830M",
"/b/OL5550831M",
"/b/OL5876614M",
"/b/OL5888524M",
"/b/OL6088137M",
"/b/OL6088190M",
"/b/OL6272774M"
]
}</pre>
</div>
</td></tr></table>
</div>
### Performance Issues
To have a bound on the amount of resources consumed by a query, the runtime of each query is limited to 60 sec. Any query that takes longer is aborted.
<br /><br /><br />
|
