Skip to content

E
edx-platform
Commit a1394e99 by Carol Tong
Options

Add documentation for Courses API

parent 0b6da4cd
Showing with 346 additions and 24 deletions
docs/en_us/platform_api/source/courses/courses.rst 0 → 100644
.. _Courses API Courses Resource:
########################################
Courses API Courses Resource
########################################
With the Courses API **Courses** resource, you can complete the
following tasks.
.. contents::
:local:
:depth: 1
.. _Get a list of courses:
**********************
Get a List of Courses
**********************
The endpoint to get a list of courses is ``/api/courses/v1/courses/``.
=====================
Use Case
=====================
Get a list of the courses that are visible to a specific user. If a username
is not supplied, an anonymous user is assumed. Users with course staff
permissions can specify other users' usernames.
=====================
Request Format
=====================
GET /api/courses/v1/courses/
Example:
GET /api/courses/v1/courses/?username=anjali
.. _Courses Query Parameters:
=====================
Query Parameters
=====================
* username (optional) - The username of the user for whom the course data is
being accessed. If the request is made for an anonymous user, username is
not required. Only users with course staff permissions can specify other
users' usernames.
* org (optional) - A code for an organization; case-insensitive. Example:
"HarvardX". If ``org`` is specified, the list of courses includes only
courses that belong to the specified organization.
* mobile (optional) - If specified, the list of courses includes only courses
that are designated as ``mobile_available``.
.. _Courses Response Values:
=====================
Response Values
=====================
The following fields are returned with a successful response.
All date/time fields are in ISO 8601 notation.
* effort: A textual description of the weekly hours of effort expected in the
course.
* end: The date and time that the course ends.
* enrollment_end: The date and time that enrollment ends.
* enrollment_start: The date and time that enrollment begins.
* id: A unique identifier of the course; a serialized representation of the
opaque key identifying the course.
* media: An object that contains named media items, including the following
objects.
* course_image: An image to show for the course.
* uri: The location of the image.
* course_video: A video about the course.
* uri: The location of the video.
* name: The name of the course.
* number: The catalog number of the course.
* org: The name of the organization that owns the course.
* overview: An HTML textual description of the course.
* short_description: A textual description of the course.
* start: The date and time that the course begins.
* start_display: The start date of the course, formatted for reading.
* start_type: Indicates how ``start_display`` was set. Possible values are:
* "string": Manually set by the course author.
* "timestamp": Generated from the ``start`` timestamp.
* "empty": No start date is specified.
* pacing: The type of pacing for this course. Possible values are
``instructor`` and ``self``.
* course_id: The course key. This field might be returned but is deprecated.
You should use ``id`` instead.
==============================================================
Example Response Showing The List of Courses Visible to a User
==============================================================
.. code-block:: json
{
"media": {
"course_image": {
"uri": "/c4x/edX/example/asset/just_a_test.jpg",
"name": "Course Image"
}
},
"description": "An example course.",
"end": "2015-09-19T18:00:00Z",
"enrollment_end": "2015-07-15T00:00:00Z",
"enrollment_start": "2015-06-15T00:00:00Z",
"id": "edX/example/2012_Fall",
"name": "Example Course",
"number": "example",
"org": "edX",
"start": "2015-07-17T12:00:00Z",
"start_display": "July 17, 2015",
"start_type": "timestamp"
}
.. _Get the details for a course:
*************************
Get Details for a Course
*************************
The endpoint to get the details for a course is
``/api/courses/v1/courses/{course_key}/``.
=====================
Use Case
=====================
Get the details for a course that you specify using a course key.
=====================
Request Format
=====================
GET /api/courses/v1/courses/{course_key}
Example:
GET /api/courses/v1/courses/edX%2FDemoX%2FDemo_Course
=====================
Query Parameters
=====================
* username (optional) - The username of the user for whom the course data is
being accessed. If the request is made for an anonymous user, username is
not required. Only users with course staff permissions can specify other
users' usernames.
=====================
Response Values
=====================
:ref:`Response values<Courses Response Values>` for this endpoint are the same
as those for :ref:`Get a list of courses`.
=========================================================
Example Response Showing Details of a Specified Course
=========================================================
The following example response is returned from this request:
GET /api/courses/v1/courses/edX%2FDemoX%2FDemo_Course
.. code-block:: json
{
"effort": null,
"end": "2015-08-08T00:00:00Z",
"enrollment_start": "2015-01-01T00:00:00Z",
"enrollment_end": "2015-05-01T00:00:00Z",
"id": "edX/DemoX/Demo_Course",
"media": {
"course_image": {
"uri": "/c4x/edX/DemoX/asset/images_course_image.jpg"
},
"course_video": {
"uri": null
},
},
"name": "edX Demonstration Course",
"number": "DemoX",
"org": "edX",
"short_description": null,
"start": "2015-02-05T05:00:00Z",
"start_display": "Feb. 5, 2015",
"start_type": "timestamp",
"pacing": "instructor",
"course_id": "edX/DemoX/Demo_Course",
"overview": "<p>Include your long course description here.</p>"
}
docs/en_us/platform_api/source/courses/index.rst 0 → 100644
.. _edX Platform Courses API:
#####################################
Courses API Version 1.0
#####################################
.. toctree::
:maxdepth: 2
overview
courses
blocks
docs/en_us/platform_api/source/courses/overview.rst 0 → 100644
.. _Courses API Overview:
#############################
Courses API Overview
#############################
Use the Courses API to obtain information about edX courses.
.. contents::
:local:
:depth: 1
*****************************************
Courses API Version and Status
*****************************************
The Courses API is currently at version 1.0.
************************************
Courses API Resources and Endpoints
************************************
The Courses API includes the :ref:`Courses<Courses API Courses Resource>` and
:ref:`Blocks<Courses API Blocks Resource>` resources, and supports the following
tasks, methods, and endpoints.
=================
Courses Resource
=================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get a list of courses`
- GET
- /api/courses/v1/courses/
* - :ref:`Get the details for a course`
- GET
- /api/courses/v1/courses/{course_key}/
=================
Blocks Resource
=================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get a list of the course blocks in a course`
- GET
- /api/courses/v1/blocks/ with required ``course_id`` parameter
* - :ref:`Get a list of the course blocks in a block tree`
- GET
- /api/courses/v1/blocks/{usage_id}
docs/en_us/platform_api/source/index.rst
......@@ -24,6 +24,7 @@ Supported APIs
.. toctree::
:maxdepth: 2
courses/index
enrollment/index
user/index
......
docs/en_us/platform_api/source/overview.rst
......@@ -16,5 +16,6 @@ Supported edX Platform API Modules
The following edX Platform APIs are currently supported.
* :ref:`edX Platform Courses API`
* :ref:`edX Platform Enrollment API`
* :ref:`edX Platform User API`
lms/djangoapps/course_api/blocks/views.py
......@@ -37,8 +37,19 @@ class BlocksView(DeveloperErrorViewMixin, ListAPIView):
**Parameters**:
* username: (string) The name of the user on whose behalf we want to
see the data.
* all_blocks: (boolean) Provide a value of "true" to return all
blocks. Returns all blocks only if the requesting user has course
staff permissions. Blocks that are visible only to specific learners
(for example, based on group membership or randomized content) are
all included. If all_blocks is not specified, you must specify the
username for the user whose course blocks are requested.
* username: (string) Required, unless ``all_blocks`` is specified.
Specify the username for the user whose course blocks are requested.
Only users with course staff permissions can specify other users'
usernames. If a username is specified, results include blocks that
are visible to that user, including those based on group or cohort
membership or randomized content assigned to that user.
Example: username=anjali
......@@ -99,16 +110,17 @@ class BlocksView(DeveloperErrorViewMixin, ListAPIView):
* root: The ID of the root node of the requested course block
structure.
* blocks: A dictionary that maps block usage IDs to a collection of
information about each block. Each block contains the following
* blocks: A dictionary or list, based on the value of the
"return_type" parameter. Maps block usage IDs to a collection of
information about each block. Each block contains the following
fields.
* id: (string) The usage ID of the block.
* type: (string) The type of block. Possible values include course,
chapter, sequential, vertical, html, problem, video, and
discussion. The type can also be the name of a custom type of block
used for the course.
* type: (string) The type of block. Possible values the names of any
XBlock type in the system, including custom blocks. Examples are
course, chapter, sequential, vertical, html, problem, video, and
discussion.
* display_name: (string) The display name of the block.
......@@ -119,8 +131,6 @@ class BlocksView(DeveloperErrorViewMixin, ListAPIView):
* block_counts: (dict) 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.
Returned only if the "block_counts" input parameter contains this
block's type.
* graded (boolean) Whether or not the block or any of its descendants
is graded. Returned only if "graded" is included in the
......@@ -144,17 +154,22 @@ class BlocksView(DeveloperErrorViewMixin, ListAPIView):
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_device: (boolean) Whether or not the block's
rendering obtained via block_url has support for multiple devices.
Returned only if "student_view_multi_device" is included in the
"requested_fields" parameter.
* student_view_multi_device: (boolean) Whether or not the HTML of
the student view that is rendered at "student_view_url" supports
responsive web layouts, touch-based inputs, and interactive state
management for a variety of device sizes and types, including
mobile and touch devices. Returned only if
"student_view_multi_device" is included in the "requested_fields"
parameter.
* lms_web_url: (string) The 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.
* lti_url: The block URL for an LTI consumer.
* lti_url: The block URL for an LTI consumer. Returned only if the
"ENABLE_LTI_PROVIDER" Django settign is set to "True".
"""
def list(self, request, usage_key_string): # pylint: disable=arguments-differ
......
lms/djangoapps/course_api/views.py
......@@ -17,7 +17,7 @@ class CourseDetailView(DeveloperErrorViewMixin, RetrieveAPIView):
"""
**Use Cases**
Request information on a course
Request details for a course
**Example Requests**
......@@ -27,12 +27,11 @@ class CourseDetailView(DeveloperErrorViewMixin, RetrieveAPIView):
Body consists of the following fields:
* blocks_url: Used to fetch the course blocks
* effort: A textual description of the weekly hours of effort expected
in the course.
* end: Date the course ends
* enrollment_end: Date enrollment ends
* enrollment_start: Date enrollment begins
* end: Date the course ends, in ISO 8601 notation
* enrollment_end: Date enrollment ends, in ISO 8601 notation
* enrollment_start: Date enrollment begins, in ISO 8601 notation
* id: A unique identifier of the course; a serialized representation
of the opaque key identifying the course.
* media: An object that contains named media items. Included here:
......@@ -46,16 +45,17 @@ class CourseDetailView(DeveloperErrorViewMixin, RetrieveAPIView):
Note: this field is only included in the Course Detail view, not
the Course List view.
* short_description: A textual description of the course
* start: Date the course begins
* start: Date the course begins, in ISO 8601 notation
* start_display: Readably formatted start of the course
* start_type: Hint describing how `start_display` is set. One of:
* `"string"`: manually set
* `"timestamp"`: generated form `start` timestamp
* `"empty"`: the start date should not be shown
* `"string"`: manually set by the course author
* `"timestamp"`: generated from the `start` timestamp
* `"empty"`: no start date is specified
* pacing: Course pacing. Possible values: instructor, self
Deprecated fields:
* blocks_url: Used to fetch the course blocks
* course_id: Course key (use 'id' instead)
**Parameters:**
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment