The Reading API for this site allows users and apps to access book and chapter objects in JSON format. The url for the Read API is the site's base url plus "api.php" (e.g., https://edtechbooks.org/api.php).
Two types of objects may be requested via the Read API: (a) a book or (b) a chapter. Book calls require the book variable, which will look up the book based upon the unique "short name" provided. Chapter calls require both the book variable and the chapter variable, which will look up the chapter based upon the unique "short name" for each.
Usage
The API may be used to display content in your own site or app provided that you include proper attribution for the content and the hosting site. This can easily be done by displaying the suggested citation for the book or chapter.
Data Structure
The platform uses three main data object types: authors, books, and chapters. Other objects are also sometimes used, such as glossary terms.
Variables
| Variable |
Type |
Status |
Default |
Description |
| action |
string |
optional |
read |
Specify the action to be performed. If no action is specified, the API will attempt to return a book or chapter. |
| book |
string |
optional |
- |
The short name of the book, which is the path of the book's base or cover url. For example: http://edtechbooks.org/qualitativeinquiry |
| chapter |
string |
optional |
- |
The short name of the chapter, which is the last part of the chapter's url. For example: http://edtechbooks.org/qualitativeinquiry/storyanalysis |
| glossary_term |
string |
optional |
- |
The anchor name of the glossary term. |
| glossary_term_id |
int |
optional |
- |
The term_id of the glossary term. |
| term |
string |
optional |
- |
Specify a search term for some actions. |
| limit |
integer |
optional |
10 |
Specify a limit. Maximum: 200 |
| offset |
integer |
optional |
0 |
Specify an offset for pagination purposes. |
| key |
string |
unused |
- |
The Reading API currently does not require a key. |
Actions
Options for the action variable include the following:
- read (default; requires book; also uses chapter)
- analytics (requires book; also uses chapter)
- search_authors (requires term)
- search_books (uses term, but returns full list of books if no term is provided)
Examples
To request reference information for all books in the site, the API call would be:
https://edtechbooks.org/api.php?action=search_books&offset=0&limit=200
To request the book object for https://edtechbooks.org/k12handbook, the API call would be:
https://edtechbooks.org/api.php?book=k12handbook
To request the chapter object for https://edtechbooks.org/k12handbook/connectivism, the API call would be:
https://edtechbooks.org/api.php?book=k12handbook&chapter=connectivism
To request the glossary term "constructivism" in https://edtechbooks.org/k12handbook, the API call would be:
https://edtechbooks.org/api.php?book=k12handbook&glossary_term=constructivism
To search for books with the term "education" in the title, the API call would be:
https://edtechbooks.org/api.php?action=search_books&term=education
To request the analytics for the chapter https://edtechbooks.org/k12handbook/connectivism, the API call would be:
https://edtechbooks.org/api.php?book=k12handbook&chapter=connectivism&action=analytics
To get more than the default referer limit (10), add a referer_limit variable to the url.
https://edtechbooks.org/api.php?book=k12handbook&chapter=connectivism&action=analytics&referer_limit=20
To search for an author with the name "Royce," the API call would be:
https://edtechbooks.org/api.php?action=search_authors&term=royce
App Structure Example
An example of a simple app that accessed books on this site might follow this structure:
- A home page that called
https://edtechbooks.org/api.php?action=search_books to return all available books (with short names). You can use the offset and limit variables to iterate through the entire list.
- If a book is selected,
https://edtechbooks.org/api.php?book=[book_short_name_here] is called with the appropriate short name.
- If a chapter is selected,
https://edtechbooks.org/api.php?book=[book_short_name_here]&chapter=[chapter_short_name_here] is called with the appropriate short name.
An example of an app that could download the entire available database might follow this structure:
- A home page that called
https://edtechbooks.org/api.php?action=search_books to return all available books (with short names). You can use the offset and limit variables to iterate through the entire list.
- Download each book by accessing its short name at
https://edtechbooks.org/api.php?book=[book_short_name_here]
- Download each chapter by iterating through the chapter briefs for each book returned in Step 2 via
https://edtechbooks.org/api.php?book=[book_short_name_here]&chapter=[chapter_short_name_here]
An example of an app that could search for an author and return author information might follow this structure:
- Search for the author by name
https://edtechbooks.org/api.php?action=search_authors&term=kimmons
- Retrieve the author object by id
https://edtechbooks.org/api.php?action=authors&author_ids=1
Authentication
The API currently does not require a key, but that could change as the site and its services develop. For more information on future plans for the API or to request a key, please contact the site administrator.