Diff on /dev/docs/restful_api

History

View

Open Library RESTful API → Diff

Added

Modified

Removed

Not changed

Revision 10 by George December 4, 2009

Revision 21 by jachamp September 1, 2023

body

0	<style type="text/css">	0	<style type="text/css">
...		...
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	...	119	...
...		...
125		125
126	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/a/OL1A&limit=2'	170	$ curl 'http://openlibrary.org/query.json?type=/type/edition&authors=/authors/OL1A&limit=2'
127	[	171	[
128	{	172	{
129	"key": "/b/OL1M"	173	"key": "/books/OL1M"
130	},	174	},
131	{	175	{
132	"key": "/b/OL4731M"	176	"key": "/books/OL4731M"
133	}	133	}
...		...
138	# curl fails because it doesn't escape query parameter	138	# curl fails because it doesn't escape query parameter
139	$ 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}'
140	[	184	[
141	{	185	{
142	"key": "/b/OL1M",	186	"key": "/books/OL1M",
143	"title": "Kabit\u0101."	187	"title": "Kabit\u0101."
144	},	188	},
145	{	189	{
146	"key": "/b/OL4731M",	190	"key": "/books/OL4731M",
147	"title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."	191	"title": "Sacci Ra\u0304utara\u0304y\u0307a grantha\u0304bal\u0323i\u0304."
148	}	192	}
149	]	193	]
150		194
151	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.
152		196
153	<a name="history"></a>	197	<a name="history"> </a>
154	## History	198	## History
155		199
156	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.
157		201
158	$ curl http://openlibrary.org/b/OL1M.json?m=history	202	$ curl http://openlibrary.org/books/OL1M.json?m=history
159	[	159	[
...		...
166	]	166	]
167	$ 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
168	[	168	[
...		...
182		182
183	$ 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
184	[	184	[
...		...
198		198
		243	<a name="recent_changes"> </a>
199	## Recent Changes	199	## Recent Changes
...		...
210	]	210	]
211	$ curl -H 'Accept: application/json' http://openlibrary.org/recentchanges	256	$ curl -H 'Accept: application/json' https://openlibrary.org/recentchanges
212	[	212	[
...		...
223	...	223	...
224	$ 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
225		270
226	Support for RSS and Atom formats will be available soon.	271	Support for RSS and Atom formats will be available soon.
227		272
228	<a name="login"></a>	273	<a name="login"> </a>
229	## Login	274	## Login
230		275
231	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.
232		277
233	$ 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
234	HTTP/1.1 200 OK	279	HTTP/1.1 200 OK
235	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=/
236		281
237	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.
238		283
239	<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>
240	## Save	240	## Save
...		...
247		247
248	<a name="status_codes"></a>	295	<a name="status_codes"> </a>
249	## Status codes	249	## Status codes
...		...
273	Debug information about the error may be provided in the response to help trouble-shooting the issue.	273	Debug information about the error may be provided in the response to help trouble-shooting the issue.

edit