Versions Compared

Old Version 1

changes.mady.by.user Jeremy Ristau

Saved on

compared with

New Version 2

changes.mady.by.user Jeremy Ristau

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
minLevel1
maxLevel7

Problem statement

We seek to empower course owners to maintain their content on any platform, while programmatically co-hosting that content on the edX platform. This includes the following:

...

2U is driving toward an 80/20 solution that may not be able to replicate every distinct edX course run feature possible, but that with bounded effort allows a great many use cases to be accomplished programmatically within the 2023 calendar year.

MVP Definition

From an MVP perspective, it is essential that co-hosting work with:

...

This capability must also extend to updates made to course runs, and not be limited to one-time ports. That is, content owners ought to be able to update from the source on-demand, without loss on the edX platform of any course run information.

Technical Decisions

At this time, 2U has made three decisions:

  1. Adopt OLX as the basis for how content is communicated to the edX platform.

    1. This is the most complex and consequential of the decisions. Factors that most influenced this decision include:

      1. Desire not to have to support multiple representations

      2. Reduction of work and risk by not having to design an abstraction layer, get buy-in for that layer, and then implement that layer (e.g., a new json-based representation)

      3. Placing the burden of resolving capability gaps or paradigm incompatibilities closest to content owners, as it is content owners who decide what compromises are acceptable

  2. Rely on existing readthedocs documentation to make new studio content management APIs immediately usable without need of new documentation for all remaining XBlock types.

    1. 2U will draft guidance on how to set XBlock settings with OLX for all XBlock types that are in the MVP Definition

  3. Enhance existing import/export API and xblock APIs to enable the maintenance of both course runs and components.

    1. This is to enable efficient implementation of both course-wide and fine-grained use cases

Content data transfers

An API exposing content creation capabilities may be written in terms of edX-native constructs, partner-native-constructs, or in terms of a generic capabilities abstraction. We propose to port content using OLX constructs, the edX-native choice.

...

Working with OLX this way entails using the readthedocs documentation to create sample content on studio, exporting that sample content, and then using the generated OLX as a template for the porting work itself. (More on this in the “Self-documenting API” section below).

Self-documenting API

Course run content and settings will be encoded in this API with Open Learning XML (OLX) encoding. We argue here that this decision affords instant breadth in terms of the types of content and settings that the API offers, but the decision admittedly shifts a complexity burden onto content owners.

...

All that’s needed for a “self-documenting” solution is an API that allows creation and editing of course run content via OLX files, a-la the import/export capability. It is self-documenting in that the API documentation need not document an XBlock type’s idiosyncrasies for the type to be usable via the API.

Import/export extensions

The existing import/export functionality applies at the course run level only: as and end user, you either export an entire course run, or you import (and replace) an entire course run. The course run you import content into must already exist, and prior content is replaced.

...

edX courses runs are composed of XBlocks. An XBlock is a package that defines how a component is presented to the student, how it behaves, and how it is stored. The above discussion based on OLX representations frames porting work in term of existing XBlock types. While that’s a valid assumption in most cases, new XBlock types may be added as a measure of last resort to resolve capability gaps or paradigm incompatibilities.

Operational “-ilities”

Concurrency

API-driven changes to a course run may need to occur in the context of a locking mechanism: programmatic access to a course run will be limited to one client at a time. Locks will time out after some period of inactivity. 2U acknowledges that lock maintenance is expensive and error prone, other options are also being explored.

Error Handling

  • OLX with improper syntax will be reported as such, with the offending unit identified. The end user always has the option of experimenting with the OLX content, manually importing iterations into a test course, until satisfied.

  • Configuration errors reported by XBlock logic and course run validation will be passed on verbatim to the API client.

  • Timeout conditions on bulk processing will be fatal and will be reported. The end user has the choice of subdividing the bulk operations into finer-sized units.

  • Bulk operations may take minutes or tens of minutes. The API will provide a mechanism to periodically reveal progress during this wait.

  • 2U-internal logging tools will capture all reported errors.

Observability

Analytics will be collected by 2U-internal Observability Tools to identify usage levels by application ID, by API, by XBlock type, and by course run. The analytics is to be rich enough to measure historical API performance and to allow detection of congestion problems.

Visibility into ported XBlock types and the settings that apply to them will exist. This is intended to assist with bug reports; also, it will be useful to know whether a bug is a first instance or not, and to have breadcrumbs as to earlier usage.

Resiliency

  • The API will not be chatty (i.e., it will offer bulk operations).

  • Calls into the API from a client will be throttled.

  • The burden of handling duplicate requests will fall to the client.

Scalability

The design is to be scalable for performance/throughput, but need not be dynamically scalable. That is, static reservation of more resources for programmatic content creation and editing is acceptable.

Security

  • Applications accessing the Studio API will need to register with CMS.

  • Authentication and authorization will be OAuth2-based. Authorization will be for the same course creation/modification privileges the end user would have if on studio directly.

  • We have not yet identified the need for any new scopes.

Testability

  • Automated tests should allow us to publish at any time a set of XBlock types and settings that are known to pass on a syntax basis.

  • Automated tests should cause errors generated by the API to fire, to ensure that they, too, are working.

  • Automated testing of features controlled by XBlock-specific settings is out of scope.

Risks

Capability gaps

A randomly selected course from another CMS may call for capabilities not currently supported in any edX platform XBlock. Porting such a course would either be a lossy process or would require the development of new XBlocks. Our project plan does not currently provide for creation of new XBlocks. How often this will prevent a course from being ported is unknown.

Paradigm-shift incompatibilities

Per the “Solution Alternatives” section below, mapping on-edX course paradigms onto edX course paradigms may sometimes be lossy.

In extreme cases, a capability required to port a given course may be offered by an edX platform XBlock, but its paradigm may differ so much from the source platform’s paradigm as to be effectively unusable. This results in the same risk as with a capability gap.

Inversion of Control

This API will provide more scriptable control to content creators and with it comes more opportunity to do the wrong thing. There is a risk that operators will “shoot themselves in the foot” in a very bad way. The Operational “-ilities” section attempts to mitigate as many of those risks as possible within 2U’s scope of effort.