API Documentation

Overview

  • Endpoint is /api/v1/
  • Unless otherwise specified, the default format of the response is application/json.
  • Only public book information is returned in a response, including only books and posts that are marked as public/published.

Valid Calls

{http://yourdomain.com}/api/v1/

GET Resource Parameters Implementation Notes
/books titles, subjects, authors, licenses, keywords, limit, offset Gets information about a collection of books in a Pressbooks instance.
Limit of 100 returned unless otherwise specified (ie.?limit=0)
/books/{book_id} titles, authors, licenses, limit, offset Gets information about a specific book.
If parameters are passed, it returns information about chapters from that book

Response:

{
"success":true,
"data":{
	"3":{
		"book_id":"3",
		"book_url":"http:\/\/localhost\/pressbooks\/dbdesign\/",
		"book_meta":{
			"pb_cover_image":"http:\/\/localhost\/pressbooks\/dbdesign\/assets\/images\/default-book-cover.jpg",
			"pb_book_copyright":"Brad Payne",
			"pb_title":"Database Design",
			"pb_short_title":"short title",
			"pb_subtitle":"subtitle here",
			"pb_author":"Brad Payne",
			"pb_author_file_as":"Payne, Brad",
			"pb_publisher":"publisher here",
			"pb_publisher_city":"publisher city",
			"pb_publication_date":"1401580800",
			"pb_language":"en",
			"pb_copyright_year":"2013",
			"pb_copyright_holder":"Brad Payne",
			"pb_book_license":"cc-by-sa",
			"pb_custom_copyright":"Custom Copyright Notice here",
			"pb_about_140":"Book Tagline here",
			"pb_about_50":"Short Description here",
			"pb_about_unlimited":"Long Description here",
			"pb_editor":"Editor here",
			"pb_keywords_tags":"database, computers, design",
			"pb_hashtag":"#hashtag here",
			"pb_list_price_print":"$15.00",
			"pb_list_price_pdf":"$0.00",
			"pb_list_price_epub":"$0.00",
			"pb_list_price_web":"$0.00",
			"pb_bisac_subject":"Science & Technology, Teaching Methods & Materials, EDUCATION"
		},
		"book_toc":{
			"front-matter":{
				"4":{
					"post_id":4,
					"post_title":"Introduction",
					"post_link":"http:\/\/localhost\/pressbooks\/dbdesign\/front-matter\/introduction\/",
					"post_license":"cc-by",
					"post_authors":"Jack Black"
				}
			},
			"part":[{
				"post_id":3,
				"post_title":"Main Body",
				"post_link":"http:\/\/localhost\/pressbooks\/dbdesign\/part\/main-body\/",
				"chapters":{
					"18":{
						"post_id":18,
						"post_title":"About the Author",
						"post_link":"http:\/\/localhost\/pressbooks\/dbdesign\/chapter\/about-the-author\/",
						"post_license":"cc-by-nd",
						"post_authors":"Ned Flanders"
					},
					"20":{
						"post_id":20,
						"post_title":"Characteristics and Benefits of a Database",
						"post_link":"http:\/\/localhost\/pressbooks\/dbdesign\/chapter\/c-and-b-of-a-database\/",
						"post_license":"cc0",
						"post_authors":"Christopher Hitchens"
					},
				}],
			"back-matter":{
				"7":{
					"post_id":7,
					"post_title":"Appendix",
					"post_link":"http:\/\/localhost\/pressbooks\/dbdesign\/back-matter\/appendix\/",
					"post_license":"cc-by-sa",
					"post_authors":"David Suzuki"
				}
			}
		}
	}
}
}

Parameters

Name Format Acceptable Values Description
titles string comma separated values limit of 5
partial string match
/books?titles=value1,value2 searches book titles within a collection, specified at "pb_title"
/books/{book_id}?titles=value1,value2 searches chapter titles within a book, specified at "post_title"
subjects string comma separated values limit of 5
partial string match
/books?subjects=value1,value2 searches against values found in "pb_bisac_subject"
authors string comma separated values limit of 5
partial string match
/books?authors=brad,jack searches for book authors within a collection, specified at "pb_author"
/books/{book_id}?authors=brad,jack searches for chapter authors within a book, specified at "post_authors"
licenses string cc-by
cc-by-sa
cc-by-nc
cc-by-nc-sa
cc-by-nd
public-domain
all-rights-reserved
limit of 5
exact string match
/books?licenses=cc-by,cc-by-sa searches for book licenses within a collection, specified at "pb_book_license"
/books/{book_id}?authors=brad,jack searches for chapter licenses within a book, specified at "post_license"
keywords string comma separated values limit of 5
partial string match
/books?keywords=value1,value2 searches against values found in "pb_keywords_tags"
limit integer positive or negative integers 0 = unlimited results
positive integer returns results starting from the beginning
negative integer returns results starting from the end
offset integer positive or negative integer positive integer returns results, offset from the beginning
negative integer returns results, offset from the end
json integer 1 json response is returned whether this parameter is specified, or not
?json=1 returns a json response
xml integer 1 ?xml=1 returns an xml response

Examples

  • {http://yourdomain}/api/v1/books?subjects=biology,technology&keywords=education&limit=3
    returns all books in a collection with either subject 'biology' OR 'technology' AND the keyword 'education', limit the results to 3 starting from the beginning (only return the first 3 results).
  • {http://yourdomain}/api/v1/books/3?titles=data&licenses=cc-by,cc-by-sa&offset=-1
    returns all chapters from the book with id = 3 whose title contains the substring 'data' AND is licensed under 'cc-by' OR 'cc-by-sa', offset from the end (return everything but the last result).

Error Messages

All error messages are returned in json format and refer back to this documentation. Errors will return success:false. For example:

{
"success":false,
"data":{
	"messages":"There are no records that can be returned with the request that was made",
	"documentation":"\/api\/v1\/docs"
	}
}