Versions Compared

Old Version 88

changes.mady.by.user Nimisha Asthagiri

Saved on

compared with

New Version Current

changes.mady.by.user Nimisha Asthagiri

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This is a detailed design document on the Course Blocks API and how it enables xBlocks on Mobile.

...

Here are the basic technical requirements:

  • FUTURE (for Course Navigation): Although the course structure supports an arbitrary navigational depth, the client UI should be able to enforce a maximum navigational depth.  This allows for a clear and consistent user experience through the course, if/when the UX chooses to do so.
  • The payload needs to be user-specific, while honoring roles, group pathways, and individual differentials.

  • It should be possible to delegate the rendering of an xBlock to the client by providing the xBlock's raw data (e.g., in JSON).  This allows us to support:

    • a user experience that is native to the device.

    • a different design of the xBlock's (student) view.
  • It should be possible to render the student view of an individual xBlock without the envelope of the LMS chrome.
  • APIs should follow the edX REST API Conventions.
  • The response payload for a Course Blocks API should be consistent with the existing Course Structure API that was reviewed and approved by the Architecture Council.

...

 Having a multitude of endpoints and API resources for each type of data for a course can be both hard to maintain and difficult to understand for API consumers.  Instead, we have designed a top-level resource for courses, as follows.  The API is now documented on read-the-docs.

Note: The current Course Structure API would be renamed as below.

endpointdescriptionparametersresponse info

course catalog
api/courses/v1/courses/  


Status: Implemented

returns a list of courses and their metadata

use cases:

  • course search page, course catalog - by accessing the endpoint as a non-privileged/anonymous user or passing in target user's username as a parameter
  • external privileged system enumerating through courses - by accessing the endpoint as a privileged user

note: for a list of enrolled courses, the enrollment API should be used instead.

  • user for a user-specific data
  • sort by date, name, org, etc.
  • paging
  • filters: mobile_only, category, etc.
  • if no user parameter is given, it lists all possible courses that the requested user can view.
  • if a user parameter is given, it lists only those courses that the target user can view.
  • each course's data response is as described in the course meta data endpoint below.

course metadata
api/courses/v1/courses/<course_id>


Status: Implemented

returns the meta data for the requested course

use cases: "course profile" information, like for a post on a social media page

user

id
name
start
end
image_url
updates_url
handouts_url
blocks_url
lms_web_url
about_url (drupal site)

course blocks
/api/courses/v1/blocks/<root_block_usage_id>/
?depth=all

or

/api/courses/v1/blocks/?course_id=<course_id>


Status: Implemented 

returns the blocks in the course starting at the requested root.

use cases: for accessing course content

user-specific
user=anjali

user-specific, mobile fields
user=anjali,
&fields=graded,format,multi_device,
&block_counts=video,
&student_view_data=video,
&student_view_data.video=mobile_low

all blocks for insights
fields=graded,format

 

FUTURE parameters
type - filter by block type

views other than student_view		A dictionary of blocks, with the key being the block’s usage_id and the value being the block’s data (as defined in the block data endpoint below).

course block data 
/api/courses/v1/blocks/<usage_id>/


Status: Not yet implemented

returns the data for the requested blocksame as for the course blocks endpoint

id
type
display_name
children
lms_web_url
olx_data
student_view_url
student_view_data

plus, requested fields that are supported, such as:

student_view_multi_device
graded
format
block_counts

course navigation
 

 

Status: Not approved

We will have FUTURE support for course navigation once it is designed.

returns the navigation information of the course starting at the requested root

use cases: for displaying the course hierarchy in a limited view with navigation constraints (e.g., rendering all blocks in a 3-level course hierarchy)

  

Block Rendering: Web, Responsive, and Native

...

The crux of this proposal is the introduction of the Course Blocks endpoint that supports student-facing data for presenting course block content.  This section provides design considerations and then details of the endpoint for a user-specific request.  The API is now documented at read-the-docs.

FUTURE: Why Course Navigation?

We will have FUTURE support for course navigation once it is designed.

This proposal decouples the navigation of a course from the rest of the blocks in the course by considering Navigation as a formatting strategy that is applied to the course blocks.  In future extensions, one can envision different navigational strategies including flattening or deepening of the course structure or supporting a choose-your-own-adventure experience.

Additionally, in order to support clients that present a limited N-tier hierarchy of the course structure (e.g., Section->Subsection->Unit), the Navigation strategy can provide this information.  The server-side provides the logic of collapsing the DAG into an N-tiered hierarchy, allowing the client to be a generic consumer of this strategy.

No Pagination?

We made a conscious decision to not paginate this endpoint (for now) although its data could be potentially large, for the following reasons:

...

When there's an access control failure, the response payload will contain information about the specific error as described in LMS has_access interface design.  It includes an error_code, developer_message, and a user_message.

...

  • It is optimized for reducing the number of round trips by:
    • including all the blocks in the course in the payload
    • having an endpoint that combines the block and navigation information
  • It allows managing the payload size by providing optional parameters to specify which fields to return.
  • The response time is optimized as described in Fast Course Block Trees: Tree Transformers.

Resources

Block

FieldTypeDescription
idstring

The usage-id of the block.

ex: "block-v1:edX+DemoX+Demo_Course+type@problem+block@45d46192272c4f6db6b63586520bbdf4"

typestring

The type of block. Possible values include course, chapter, sequential, vertical, html, problem, video, and discussion. The type can also be any custom block type used by the course.

display_namestringThe display name of the block.
childrenlist[string]

If the block has child blocks, a list of IDs of the child blocks.

Optional: Returned only if "children" is included in the "fields" parameter.

student_view_datadict

The JSON data of the student_view of this block.

Optional: Returned only if the "student_view_data" input parameter contains this block's type.

student_view_urlstring

The URL to retrieve the HTML rendering of this block's student view.  The HTML could include CSS and Javascript code. This field can be used in combination with the student_view_multi_device field to decide whether to display this content to the user.

This URL can be used as a fallback if the student_view_data for this block type is not supported by the client or the block.

student_view_multi_deviceboolean

Whether or not the block's rendering obtained via student_view_url is responsive.

Optional: Returned only if "student_view_multi_device" is included in the "fields" parameter.

lms_web_urlstringThe URL to the navigational container of the xBlock on the web LMS. This URL can be used as a further fallback if the student_view_url and the student_view_data fields are not supported.
formatstring

The assignment type of the block. Possible values can be "Homework", "Lab", "Midterm Exam", and "Final Exam".

Optional: Returned only if "format" is included in the "fields" parameter.

Aggregate values

gradedboolean

Whether or not the block or any of its descendants is graded.

Optional: Returned only if "graded" is included in the "fields" parameter.

block_countsdict

For each block type specified in the block_counts parameter to the endpoint, the aggregate number of blocks of that type for this block and all of its descendants.

Optional: Returned only if the "block_counts" input parameter contains this block's type.

...

MethodDescription
GET

Retrieves the blocks in a course

 Query parameters:

  • student_view_data: (list) Indicates for which block types to return student_view_data.
    example: student_view_data=video
  • student_view_data.<block_type>.context: (string) Data to be passed as the "context" parameter to the given block type's student_view_data method.
    example: student_view_data.video.context="mobile_low"
  • block_counts: (list) Indicates for which block types to return the aggregate count of the blocks.
    example: block_counts=video,problem
  • fields: (list) Indicates which additional fields to return for each block.
    default: children,graded,format,student_view_multi_device
  • user: (string) the username of the user that should be used as the context of the request. 
    The response is created according to this user's access, group affiliation, and individual differentials.

Returns:

  • root: (string) The usage-id of the root block in the response.
  • blocks: (dict) A dictionary where the key is the block's usage-id and the value is the block's data.  
    • The fields returned for the block are described in the Block table above. 

Click for example (older version of the API)


FUTURE: NAVIGATION

MethodDescription
GET

We will have FUTURE support for course navigation once it is designed.

Returns a navigation strategy for the course to create a course outline until the requested maximum depth.  All nodes past the maximum depth are collapsed into their container's descendants field.

 Query parameters:

  • navigation_depth (integer) Indicates how far deep to traverse into the course hierarchy before bundling all the descendants.
    default: 3 since typical navigational views of the course show a maximum of chapter->sequential->vertical.
    example: navigation_depth=3

Returns:

  • root: (string) The usage-id of the root block in the course.
  • navigation: (dict) A dictionary where the key is the block's usage-id and the value is the block's data.
    • Only the "descendants" field of the block is returned. The "descendants" field is described in the Block table above.

Click for example

Example of API call from Mobile Apps

...

  • The objective is to design a generic set of APIs that can be used by various clients, including the mobile apps.  If further mobile-specific optimizations are later required, we can create a thin layer above for the mobile-specific ones.
  • The generic Courses API sets a foundation as an envelope for course-related APIs.  It supports accessing both user-specific and system-wide course data.  The current CourseStructure API used by Insights will be renamed accordingly.
  • The set of APIs proposed in this document provide the ability to create a custom student view of the courseware.  The edX mobile apps will be the first consumer of this functionality.
  • FUTURE (for Course Navigation): We will have FUTURE support for course navigation once it is designed.  The decoupling of course blocks and course navigation allows for customization of navigational strategies.  Although the depth of a course hierarchy is arbitrary, the Navigation API allows consumers to create a simplified navigation UI by specifying a maximum navigation depth.
  • The Blocks API, when a user is specified, provides individualized data of the course blocks and structure, taking into consideration the user's roles, group affiliations, and user-specific differentiations.
  • The new xBlock URL allows a chromeless rendering of an individual xBlock.
  • The proposed enhancements to xBlocks (student_view_data and the @supports("multi_device") decorator) allow additional student views for xBlocks.

...