Diff on /dev/docs/restful_api

History

View

Open Library RESTful API → Diff

Added

Modified

Removed

Not changed

Revision 8 by George December 4, 2009

Revision 21 by jachamp September 1, 2023

edit

body

0	<style type="text/css">	0	<style type="text/css">
1	pre { background-color:#F0F0F0; border:1px solid #CCCBBA; padding: 10px 10px 10px 20px; }	1	pre { background-color:#F0F0F0; border:1px solid #CCCBBA; padding: 10px 10px 10px 20px; }
2	</style>	2	</style>
3		3
4	Open Library provides RESTful API for accessing resources in multiple formats.	4	Open Library provides a RESTful API for accessing resources in multiple formats.
5		5
6	* [[#content\|Content]]	6	<ul>
7	* [[#query\|Query]]	7	<li><a href="#content">Content</a></li>
8	* [[#history\|History]]	8	<li><a href="#query">Query</a></li>
9	* [[#save\|Save]]	9	<li><a href="#history">History</a></li>
10	* [[#status_codes\|Status Codes]]	10	<li><a href="#recent_changes">Recent Changes</a></li>
11		11	<li><a href="#login">Login</a></li>
12	<a name="content"></a>	12	<li><a href="#save">Save</a></li>
		13	<li><a href="#status_codes">Status Codes</a></li>
		14	</ul>
		15
		16	<a name="content"> </a>
13	## Content	17	## Content
14		18
15	To request any content, the requested format can be specified using `Accept:` header or as part of the URL.	19	To request any content, the requested format can be specified using `Accept:` header or as part of the URL.
16	The currently available formats are JSON and RDF.	20	The currently available formats are JSON and RDF.
17		21
18	$ curl http://openlibrary.org/a/OL1A.json	22	$ curl http://openlibrary.org/authors/OL1A.json
19	{	23	{
20	"name": "Sachi Rautroy",	24	"name": "Sachi Rautroy",
21	...	25	...
22	}	26	}
23	$ curl -s -H 'Accept: application/json' http://openlibrary.org/b/OL1M	27	$ curl -s -H 'Accept: application/json' https://openlibrary.org/books/OL1M
24	{	24	{
...		...
30		30
31	$ curl http://openlibrary.org/a/OL1A.json?callback=process	35	$ curl http://openlibrary.org/authors/OL1A.json?callback=process
32	process({	32	process({
...		...
38		38
39	$ curl http://openlibrary.org/b/OL6807502M.rdf	43	$ curl https://openlibrary.org/books/OL6807502M.rdf
40	<rdf:Description rdf:about="http://openlibrary.org/b/OL6807502M">	44	<rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
41	<!-- authors -->	45	<!-- authors -->
42	<bibo:authorList rdf:parseType="Collection">	46	<bibo:authorList rdf:parseType="Collection">
43	<rdf:Description rdf:about="http://openlibrary.org/a/OL1518080A">	47	<rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
44	<rdf:value>Lawrence Lessig</rdf:value>	44	<rdf:value>Lawrence Lessig</rdf:value>
...		...
54	</rdf:RDF>	54	</rdf:RDF>
55	$ curl -H 'Accept: application/rdf+xml' http://openlibrary.org/b/OL6807502M.rdf	59	$ curl -H 'Accept: application/rdf+xml' https://openlibrary.org/books/OL6807502M.rdf
56	<rdf:Description rdf:about="http://openlibrary.org/b/OL6807502M">	60	<rdf:Description rdf:about="http://openlibrary.org/books/OL6807502M">
57	<!-- authors -->	61	<!-- authors -->
58	<bibo:authorList rdf:parseType="Collection">	62	<bibo:authorList rdf:parseType="Collection">
59	<rdf:Description rdf:about="http://openlibrary.org/a/OL1518080A">	63	<rdf:Description rdf:about="http://openlibrary.org/authors/OL1518080A">
60	<rdf:value>Lawrence Lessig</rdf:value>	60	<rdf:value>Lawrence Lessig</rdf:value>
...		...
66		66
67		71	Open Library also allows accessing editions of a work and works of an author using a simple URL format.
68	<a name="query"></a>	72
		73	$ curl 'http://openlibrary.org/works/OL27258W/editions.json?limit=5'
		74	{
		75	"size": 19,
		76	"links": {
		77	"self": "/works/OL27258W/editions.json?limit=5",
		78	"work": "/works/OL27258W",
		79	"next": "/works/OL27258W/editions.json?limit=5&offset=5"
		80	},
		81	"entries": [{
		82	"key": "/books/OL17987798M",
		83	"title": "Neuromantiker",
		84	...
		85	}, ...]
		86	}
		87
		88	$ curl http://openlibrary.org/authors/OL1A/works.json
		89	{
		90	"size": 16,
		91	"links": {
		92	"self": "/authors/OL1A/works.json",
		93	"author": "/authors/OL1A"}
		94	},
		95	"entries": [{
		96	"key": "/works/OL14930760W",
		97	"title": "Satchidananda Raut Roy",
		98	...
		99	}, ...]
		100	}
		101
		102	<a name="query"> </a>
69	## Query	103	## Query
70		104
71	The Query API allows querying the Open Library system for matching objects.	105	The Query API allows querying the Open Library system for matching objects.
72		106
73	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A'	107	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A'
74	[	108	[
75	{	109	{
76	"key": "/b/OL1M"	110	"key": "/books/OL1M"
77	},	111	},
78	{	112	{
79	"key": "/b/OL4731M"	113	"key": "/books/OL4731M"
80	},	114	},
81	...	115	...
82	]	116	]
83	$ curl -H 'Accept: application/json' 'http://openlibrary.org/query?type=/type/edition&authors=/a/OL1A'	117	$ curl -H 'Accept: application/json' 'https://openlibrary.org/query?type=/type/edition&authors=/authors/OL1A'
84	[	118	[
85	{	119	{
86	"key": "/b/OL1M"	120	"key": "/books/OL1M"
87	},	121	},
88	{	122	{
89	"key": "/b/OL4731M"	123	"key": "/books/OL4731M"
90	},	124	},
91	...	125	...
92	]	126	]
		127	$ curl 'http://openlibrary.org/query.json?type=/type/edition&works=/works/OL2040129W'
		128	[
		129	{
		130	"key": "/books/OL9770407M"
		131	},
		132	{
		133	"key": "/books/OL21857767M"
		134	},
		135	...
		136	]
93		137
94	Additional properties of each object can be requested by passing a query parameter with empty value.	138	Additional properties of each object can be requested by passing a query parameter with empty value.
95		139
96	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A&title='	140	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&title='
97	[	141	[
98	{	142	{
99	"key": "/b/OL1M",	143	"key": "/books/OL1M",
100	"title": "Kabit\u0101."	144	"title": "Kabit\u0101."
101	},	145	},
102	{	146	{
103	"key": "/b/OL4731M",	147	"key": "/books/OL4731M",
104	"title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."	104	"title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
...		...
110		110
111	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A&*='	155	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&*='
112	[	112	[
...		...
117	...	117	...
118	"key": "/b/OL1M",	162	"key": "/books/OL1M",
119	...	163	...
120	},	164	},
121	...	165	...
122	]	166	]
123		167
124	- Optional `limit` and `offset` parameters can be passed to limit the number of requests and offset in the results respectively.	168	Optional `limit` and `offset` parameters can be passed to limit the number of requests and offset in the results respectively. Unless any limit is specified, the responses is limited to 20 entries. Maximum allowed value of `limit` is 1000 due to performance reasons.
125	- Unless any limit is specified, the responses is limited to 20 entries. Maximum allowed value of `limit` is 1000 due to performance reasons.	169
126		170	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&limit=2'
127	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A&limit=2'	171	[
128	[	172	{
129	{	173	"key": "/books/OL1M"
130	"key": "/b/OL1M"	174	},
131	},	175	{
132	{	176	"key": "/books/OL4731M"
133	"key": "/b/OL4731M"
134	}	134	}
...		...
139	# curl fails because it doesn't escape query parameter	139	# curl fails because it doesn't escape query parameter
140	$ wget -q -O - 'http://openlibrary.org/query.json?query={"type": "/type/edition", "authors": "/a/OL1A", "title": null, "limit": 2}'	183	$ wget -q -O - 'http://openlibrary.org/query.json?query={"type": "/type/edition", "authors": "/authors/OL1A", "title": null, "limit": 2}'
141	[	184	[
142	{	185	{
143	"key": "/b/OL1M",	186	"key": "/books/OL1M",
144	"title": "Kabit\u0101."	187	"title": "Kabit\u0101."
145	},	188	},
146	{	189	{
147	"key": "/b/OL4731M",	190	"key": "/books/OL4731M",
148	"title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."	191	"title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
149	}	192	}
150	]	193	]
151		194
152	Please note that this API should not be used for bulk downloads. Dumps of the entire data are provided at regular intervals and they can be used for bulk access.	195	Please note that this API should not be used for bulk downloads. [[/developers/dumps\|Dumps of all data]] are provided at regular intervals and they should be used for bulk access.
153		196
154	<a name="history"></a>	197	<a name="history"> </a>
155	## History	198	## History
156		199
157	Change history of any object can be accessed by passing `?m=history` query parameter to the resource url.	200	Change history of any object can be accessed by passing `?m=history` query parameter to the resource url.
158		201
159	$ curl http://openlibrary.org/b/OL1M.json?m=history	202	$ curl http://openlibrary.org/books/OL1M.json?m=history
160	[	160	[
...		...
167	]	167	]
168	$ curl -H 'Accept: application/json' http://openlibrary.org/b/OL1M?m=history	211	$ curl -H 'Accept: application/json' https://openlibrary.org/books/OL1M?m=history
169	[	169	[
...		...
178		178
179	- The entries are sorted in the descending order of created time.	222	The entries are sorted in the descending order of created time.
180	- The number of entries are limited to 20 by default and a different limit can be specified by passing `limit` parameters.	223	The number of entries are limited to 20 by default and a different limit can be specified by passing `limit` parameters.
181	- Optional `offset` parameter can also be specified to get results starting from an offset.	224	Optional `offset` parameter can also be specified to get results starting from an offset.
182	- Maximum allowed value of `limit` is 1000 due to performance reasons.	225	Maximum allowed value of `limit` is 1000 due to performance reasons.
183		226
184	$ curl http://openlibrary.org/b/OL1M.json?m=history&limit=2&offset=1	227	$ curl http://openlibrary.org/books/OL1M.json?m=history&limit=2&offset=1
185	[	185	[
...		...
199		199
		243	<a name="recent_changes"> </a>
200	## Recent Changes	200	## Recent Changes
...		...
211	]	211	]
212	$ curl -H 'Accept: application/json' http://openlibrary.org/recentchanges	256	$ curl -H 'Accept: application/json' https://openlibrary.org/recentchanges
213	[	213	[
...		...
224	...	224	...
225	$ curl http://openlibrary.org/recentchanges.json?author=/user/anand&offset=20&limit=20	269	$ curl http://openlibrary.org/recentchanges.json?author=/people/anand&offset=20&limit=20
226		270
227	Support for RSS and Atom formats will be available soon.	271	Support for RSS and Atom formats will be available soon.
228		272
229	<a name="login"></a>	273	<a name="login"> </a>
230	## Login	274	## Login
231		275
232	To login to Open Library programatically, a POST request must be send to `/account/login` with `username` and `password` must be passed as a JSON dictionary.	276	To login to Open Library programatically, a POST request must be send to `/account/login.json` with your S3 `access` and `secret` keys passed as a JSON dictionary.
233		277
234	$ curl -i -H 'Content-Type: application/json' -d '{"username": "joe", "password": "secret"}' http://openlibrary.org/account/login	278	$ curl -i -H 'Content-Type: application/json' -d '{"access": "your access key", "secret": "your secret key"}' https://openlibrary.org/account/login
235	HTTP/1.1 200 OK	279	HTTP/1.1 200 OK
236	Set-Cookie: ol_session="/user/joe%2C2009-02-19T07%3A52%3A13%2C74fc6%24811f4c2e5cf52ed0ef83b680ebed861f"; Path=/	280	Set-Cookie: session="/user/username%2C2009-02-19T07%3A52%3A13%2C74fc6%24811f4c2e5cf52ed0ef83b680ebed861f"; Path=/
237		281
238	Upon successful login, a set-cookie header is returned in the response.	282	Upon successful login, a set-cookie header is returned in the response. Include this cookie with subsequent requests.
239		283
240	<a name="save"></a>	284	Every Open Library account holder has S3 keys. You can find yours <a href="https://archive.org/account/s3.php">here</a>.
		285
		286	<a name="save"> </a>
241	## Save	241	## Save
...		...
248		248
249	<a name="status_codes"></a>	295	<a name="status_codes"> </a>
250	## Status codes	250	## Status codes
...		...
274	Debug information about the error may be provided in the response to help trouble-shooting the issue.	274	Debug information about the error may be provided in the response to help trouble-shooting the issue.