Summary

The BYU University API committee has been looking for a good project to jumpstart our efforts in personal APIs. The BYU Domains project is not only providing the means to host the personal API, but the initial project as well.

Honey bee having a drink

As part of my abstract for a talk at APIStrat 2016, I wrote that BYU was interested in equipping students with personal APIs in an effort to teach them digital autonomy and make them more responsible for their learning.

Unlike others who attempted personal APIs, we're lucky in that we control both sides of the transaction. That is, we have control of the university systems and we have students who will generally use the tools we build for them. So rather than build a conventional tool to, say, create a directory, we can build one that uses the student's personal API. The university systems still work and students get a new tool that they learn to use. This is meaningful because students have a significant number and variety of interactions with the university, making it a great place to explore how architectures based on personal APIs can be designed and used.

The BYU Domains project provides a free domain name, with hosting, for every matriculated student and all faculty and staff. BYU Domains gives students an online space of their own to teach them that they can be contributors to online conversations and introduce them to the concept of self-sovereign identity. BYU Domains is a Cpanel-based hosting system. Consequently students can install numerous applications and give each a unique URL through subdomains, paths, or both. This makes a BYU Domain site a great place to host a personal API.

The BYU Domains project is creating a community directory. The purpose of the directory is to highlight uses of BYU Domains to showcase how different members of the campus community are using them. Here's University of Mary Washington's directory as an example.

The traditional way to build this would be to write some software that looks in the BYU Domains administrative database and uses the information store there to create a directory. Here's a simple diagram illustrating that approach:

community directory traditional architecture
A traditional architecture for the community directory

In this architecture the directory is tightly coupled to the specific system used to implement BYU domains. The application is dependent on the schema in the database. Any changes to the underlying system would necessitate that the directory application be updated as well.

An alternative that avoids this problem is to architect the directory application as an aggregator of information from the personal APIs of any domains that want to participate in the directory. The following diagram illustrates that architecture.

community directory api architecture A personal-API-based architecture for the community directory

In this architecture, the directory uses information from the various APIs of domains that participate. The directory application has a database for information in its domain as well as for caching information from the various APIs. We're unlikely to render a page for the directory by synchronously calling dozens of individual APIs. This design gives the directory application the traditional advantages of API-based architectures:

First, the API represents a contract upon which the directory system can depend. The contract insulates the directory from underlying implementation changes in the personal domain.

Second, the directory has access to the APIs because their owners have authorized the connection using OAuth. Domain owners can take themselves out of the directory at any point by visiting the Authorizations control panel in their domain. This eliminates the need for data sharing agreements and other information governance hurdles.

Third, domains that aren't part of the BYU Domains administrative system can still be part of the directory. For example, a faculty domain hosted by her department could just as easily be featured in the directory as one hosted by BYU Domains.

BYU's University API Committee is currently exploring how to make this work. We've had some good discussions on creating personal APIs that are built incrementally as data is needed, and done flexibly using JSON-LD markup to communicate schema information. I'm excited by the possibilities. We're also exploring API management that can run on the individual domains.

The BYU Domains Community Directory project gives us a good excuse to design and build a basic personal API application for BYU Domains. Follow-on projects, like a xAPI-responsive learning record store (LRS), will take advantage of this foundation to add portfolio data to the student's personal API. University systems can be tuned to use the profile and LRS information while leaving it all firmly in the hands of its owner.