An API for open educational resources

A presentation at WPCampus 2018 in July 2018 in St. Louis, MO, USA by Ned Zimmerman

Ned Zimmerman | @greatislander Lead Developer, Pressbooks https://pressbooks.org | @pressbooksdev

Today's session
Introduction to Pressbooks (and some acronyms)
A deep dive into the Pressbooks REST API
Practical applications, challenges, future goals

/**
A discrete collection of text (and other media)
that is designed by an author (or authors)
as an internally complete representation of an idea or set of ideas
and/or an emotion or set of emotions
and is transmitted to readers in various formats. */

An open source plugin for WordPress Multisite

WordPress includes the ability to create a network of sites by using the multisite feature. — WordPress Codex

— Front Matter (Preface, Introduction, &c.) — Parts — Chapters — Back Matter (Afterword, Appendices, &c.)

https://press.rebus.community/financialstrategy/

— PDF for print on demand & digital distribution — EPUB 2 & 3 — Kindle (MOBI) — XHTML — HTMLBook (uno ﬃ cial draft) — OpenDocument (ODT) — WordPress eXtended RSS (WXR) — Common Cartridge

What are Open Educational Resources (OERs)?

Teaching, learning and research materials in any medium, digital or otherwise, that reside in the public domain or have been released under an open license that permits no-cost access, use, adaptation and redistribution by others with no or limited restrictions. (source: 2012 Paris OER Declaration, UNESCO )

The 5R Activities (As defined by David Wiley.)

Retain - the right to make, own, and control copies of the content (e.g., download, duplicate, store, and manage)

Reuse - the right to use the content in a wide range of ways (e.g., in a class, in a study group, on a website, in a video)

Revise - the right to adapt, adjust, modify, or alter the content itself (e.g., translate the content into another language)

Remix - the right to combine the original or revised content with other material to create something new (e.g., incorporate the content into a mashup)

Redistribute - the right to share copies of the original content, your revisions, or your remixes with others (e.g., give a copy of the content to a friend)

! This material is based on original writing by David Wiley, which was published freely under a Creative Commons Attribution 4.0 license at http://opencontent.org/definition/ .

A publisher’s job is to provide good APIs for their books. — Hugh McGuire

What is an Application Programming Interface (API)?

v1 Endpoints: A Collection of Books — GET /api/v1/books — Gets information about a collection of books in a Pressbooks network. (Docs: https://opentextbc.ca/api/v1/docs/ )

v1 Endpoints: A Book — GET /api/v1/books/{book_id} — Gets information about a specific book. If parameters are passed, it returns information about chapters from that book. (Docs: https://opentextbc.ca/api/v1/docs/ )

v1 Book Endpoint https://press.rebus.community/api/v1/books/16

Thanks to Ryerson University and eCampus Ontario!

Leverage the work of the WP REST API team

Add a book metadata endpoint, conforming to an interoperable standard

Pressbooks v1 REST API {
"pb_title" : "Moby Dick" ,
"pb_authors" : "Herman Melville" }

schema.org/Book {
"@context" : "http://schema.org" ,
"@type" : "Book" ,
"name" : "Moby Dick" ,
"author" : [ {
"@type" : "Person" ,
"name" : "Herman Melville" } ] }

Support full-content Create, Read, Update, & Destroy (CRUD) operations for all custom post types

❎ Create* ✅ Read ❎ Update* ❎ Destroy* *Requires additional configuration.

Books: GET /wp-json/pressbooks/v2/books(/<id>)

Table of Contents: GET /wp-json/pressbooks/v2/toc Metadata: GET /wp-json/pressbooks/v2/metadata Content: — GET /wp-json/pressbooks/v2/front-matter(/<id>) — GET /wp-json/pressbooks/v2/parts(/<id>) — GET /wp-json/pressbooks/v2/chapters(/<id>) — GET /wp-json/pressbooks/v2/back-matter(/<id>)

inc/api !"" endpoints

$"" controller

!"" class-books.php

!"" class-metadata.php

!"" class-posts.php

!"" class-revisions.php

!"" class-search.php

!"" class-sectionmetadata.php

!"" class-terms.php

$"" class-toc.php $"" namespace.php

Controller Classes When you start go down the path of inheritance, it is important to understand that if the parent classes ever have to change at any point and your subclasses are dependent on them, you will have a major headache. — REST API Handbook

GET /wp-json/pressbooks/v2/front-matter(/<id>) GET /wp-json/pressbooks/v2/parts(/<id>) GET /wp-json/pressbooks/v2/chapters(/<id>) GET /wp-json/pressbooks/v2/back-matter(/<id>)

namespace
Pressbooks
Api
Endpoints
Controller ; class Posts extends \WP_REST_Posts_Controller {
/** * @param string $post_type Post type. */
public
function __construct ( $post_type )
{
parent ::__construct( $post_type );
$this ->namespace = 'pressbooks/v2' ;
$this ->overrideUsingFilterAndActions(); }

/**
Use object inheritance as little as possible to future-proof against WP API changes
With the exception of the abstract \WP_REST_Controller class, the WordPress API documentation
strongly suggests not overriding controllers. Instead we are encouraged to create an entirely separate
controller class for each end point.
Hooks, actions, and `register_rest_field` are fair game.
@see https://developer.wordpress.org/rest-api/extending-the-rest-api/controller-classes/#overview-the-future */
protected
function overrideUsingFilterAndActions ()
{
// The post type must have custom-fields support otherwise the meta fields will not appear in the REST API. add_post_type_support( $this ->post_type, 'custom-fields' ); add_filter( "rest_{$this->post_type}*query" , [ $this , 'overrideQueryArgs' ] ); add_filter( "rest_prepare*{$this->post_type}" , [ $this , 'overrideResponse' ], 10 , 3 ); add_filter( "rest_{$this->post_type}_trashable" , [ $this , 'overrideTrashable' ], 10 , 2 ); }

/**
Override the order the posts are displayed
@param array $args * * @return array */
public
function overrideQueryArgs ( $args )
{
// TODO: $args come from \Pressbooks\Book::getBookStructure, we should consolidate this somewhere? $args[ 'post_status' ] = 'any' ; $args[ 'orderby' ] = 'menu_order' ; $args[ 'order' ] = 'ASC' ;
return $args; }

/**
Override the response object
@param \WP_REST_Response $response * @param \WP_Post $post * @param \WP_REST_Request $request * * @return mixed */
public
function overrideResponse ( $response, $post, $request )
{
if ( $post->post_type === 'chapter' ) {
// Add rest link to associated part $response->add_link(
'part' , trailingslashit( rest_url( sprintf( '%s/%s' , $this ->namespace, 'parts' ) ) ) . $post->post_parent ); }
if ( in_array( $post->post_type, [ 'front-matter' , 'chapter' , 'back-matter' ], true ) ) {
// Add rest link to metadata $response->add_link(
'metadata' , trailingslashit( rest_url( sprintf( '%s/%s/%d/metadata' , $this ->namespace, $this ->rest_base, $post->ID ) ) ) ); }

v2 Front Matter Endpoint https://press.rebus.community/financialstrategy/ wp-json/pressbooks/v2/front-matter/157

https://press.rebus.community/financialstrategy/ wp-json/pressbooks/v2/toc

https://press.rebus.community/financialstrategy/ wp-json/pressbooks/v2/metadata

GET /wp-json/pressbooks/v2/books/{book_id}

[ {
"id" : "2" ,
"link" : "https://pressbooks.test/mobydick/" ,
"metadata" : {...},
"toc" : {
"front-matter" : [...],
"parts" : [ { ...,
"chapters" : [...] } ],
"back-matter" : [...] },
"_links" : {...} } ]

Books Book TOC Metadata Chapters Front Matter Back Matter Parts Metadata Metadata Metadata

Practical applications, challenges, and future goals

Challenges in working with the WordPress REST API

Context switching in multisite is EXPENSIVE

Enhancements to Cloning: — Attachment metadata (e.g. licenses/attribution) — Better fidelity — Support for third-party content (e.g. H5P activities)

Enhancements to Catalogs: — Improved performance — Live searching and filtering from full network collection

Ned Zimmerman
@greatislander

1 / 129

In spring 2017, the team at Pressbooks began work on an Open Publishing Infrastructure project with funding from Ryerson University. Our goals were to build a full-content REST API for Pressbooks and use it to power a new feature for users and institutions creating Open Educational Resources: the ability to clone openly-licensed books for reuse and remixing. We shipped this feature in September 2017 and have continued to iterate and improve upon it in the months since.

This session will explore:

How we extended the WordPress REST API to provide endpoints for book contents and metadata and a catalogue of books in a given network
How we built a PHP class to handle cloning books or portions of books from one Pressbooks network to another
Challenges we encountered while working with the WordPress REST API
Opportunities and future goals for the Pressbooks REST API

Resources

The following resources were mentioned during the presentation or are useful additional information.

Financial Strategy for Public Managers

An open textbook on the Rebus Community Press, made with Pressbooks.
2012 Paris OER Declaration, UNESCO

Formally adopted at the 2012 World Open Educational Resources (OER) Congress held at the UNESCO Headquarters in Paris.
Defining the "Open" in Open Content and Open Educational Resources

Material created by David Wiley, describing 5R activites of Open Content.
A Publisher’s Job Is to Provide a Good API for Books

Blog post by Pressbooks founder Hugh McGuire.
"an API for books"

Tweet from Brad Payne.
v1 REST API Documentation

Documentation for Brad Payne's Pressbooks REST API v1.
v1 REST API Book Endpoint

API response for a book in the v1 REST API.
Pressbooks working with Ryerson University on eCampusOntario grant: “Open Publishing Infrastructure”

Announcement of Pressbooks' Open Publishing Infrastructure project with Ryerson University and eCampusOntario.
WordPress REST API Handbook

Documentation on extending the WordPress REST API.
Human Made PHP Style Guide

Human Made's PHP style guide on their engineering microsite.
Human Made Coding Standards Composer package

For use in WordPress projects with Composer.
Schema.org Book Vocabulary

The Schema.org metadata vocabulary for books.
Schema.org Bibliographic Extension

Bibliographic extensions for Schema.org vocabulary.
v2 REST API Documentation

Documentation for the Pressbooks REST API v2 (contributions welcomed).
v2 REST API Post Endpoint

API response for a post (Front Matter) in the v2 REST API.
v2 REST API TOC Endpoint

API response for a book's Table of Contents in the v2 REST API.
v2 REST API Metadata Endpoint

API response for a book's metadata in the v2 REST API.
v2 REST API Book Endpoint

API response for a book in the v2 REST API.
Metadata for Sites

Changeset on Core Trac adding the wp_blogmeta table.
Sites Endpoint

Changeset on Core Trac adding a /sites REST API endpoint.

Buzz and feedback

Here’s what was said about this presentation on social media.

Really interesting seeing how @greatislander and @pressbooks is using the WordPress REST API to power open APIs for books. pic.twitter.com/EWEOtXSGxo
— Joe McGill (@joemcgill) July 13, 2018
Wonderful presentation about API structure and future in @pressbooks from @greatislander at #WPCampus. Love when presentations/conversations utterly surprise.
— Keegan🦔Long-Wheeler (@KeeganSLW) July 13, 2018
The @pressbooks API talk has given me Ideas again. Thanks, @greatislander. #wpcampus
— Patrick Johanneson (@pjohanneson) July 13, 2018
“A publisher’s job is to provide good APIs for their books” - Hugh McGuire, via @greatislander. I wish more of them saw it that way. #WPCampus
— Charles Fulton (@mackensen) July 13, 2018

An API for open educational resources

Link for this presentation:

HTML code for embedding:

Share on social media:

Resources

Financial Strategy for Public Managers

2012 Paris OER Declaration, UNESCO

Defining the "Open" in Open Content and Open Educational Resources

A Publisher’s Job Is to Provide a Good API for Books

"an API for books"

v1 REST API Documentation

v1 REST API Book Endpoint

Pressbooks working with Ryerson University on eCampusOntario grant: “Open Publishing Infrastructure”

WordPress REST API Handbook

Human Made PHP Style Guide

Human Made Coding Standards Composer package

Schema.org Book Vocabulary

Schema.org Bibliographic Extension

v2 REST API Documentation

v2 REST API Post Endpoint

v2 REST API TOC Endpoint

v2 REST API Metadata Endpoint

v2 REST API Book Endpoint

Metadata for Sites

Sites Endpoint

Buzz and feedback