Andal.LND/edx-platform
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #12311 from edx/carol/doc/DOC-2862_All

Browse Source 
DOC-2862: Add doc for Courses API
This commit is contained in:
Carol Tong
2016-05-06 17:08:32 -04:00
parent 0a61ab7549 a1394e9945
commit 26ea2dff56
8 changed files with 636 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
docs/en_us/platform_api/source/courses/blocks.rst Normal file
View File

@@ -0,0 +1,290 @@
.. _Courses API Blocks Resource:
########################################
Courses API Blocks Resource
########################################
With the Courses API **Blocks** resource, you can complete the
following tasks.
.. contents::
:local:
:depth: 1
.. _Get a list of the course blocks in a course:
****************************************
Get a List of Course Blocks in a Course
****************************************
The endpoint to get a list of course blocks in a course is
``/api/courses/v1/blocks/`` with required ``course_id`` parameter.
=====================
Use Case
=====================
Get a list of course blocks in a specified course. Response results depend on
the viewing user's permissions level within a course, as well as group
membership and individual allowances (such as due date extensions), if any.
=====================
Request Format
=====================
GET /api/courses/v1/blocks/?course_id=<course_id>
Example:
GET /api/courses/v1/blocks/?course_id=edX%2FDemoX%2FDemo_Course
&all_blocks=true&requested_fields=graded,format,student_view_multi_device
.. _Blocks Query Parameters:
=====================
Query Parameters
=====================
* all_blocks: (boolean) Provide a value of ``true`` to return all
blocks, including those that are visible only to specific learners (for
example, based on group or cohort membership, or randomized content from
content libraries). Returns all blocks only if the requesting user has course
staff permissions. If ``all_blocks`` is not specified, you must specify the
username for the user whose course blocks are requested.
* block_counts: (list) Specify the types of blocks for which to return a
count. Example: ``block_counts=video,problem``.
* block_types_filter: (list) Specify the types of blocks to be included in
results. Values are the names of any XBlock type in the system, for example:
``sequential``, ``vertical``, ``html``, ``problem``, ``video`` or
``discussion``. Example: ``block_types_filter=problem,html``.
* course_id: (string, required) The URL-encoded ID of the course whose block
data you are requesting. Example: ``course_id=edX%2FDemoX%2FDemo_Course``.
* depth: (integer or ``all``) Specify how far in the course blocks hierarchy
to traverse down. A value of ``all`` specifies the entire hierarchy. The
default value is ``0``. Example: ``depth=all``.
* requested_fields: (list) Specify the fields to return for each block, in
addition to ``id``, ``type``, and ``display_name``, which are always
returned. For the list of possible fields, see the fields listed under
``blocks`` in the :ref:`Blocks Response Values` section. Example:
``requested_fields=graded,format,student_view_multi_device``.
* return_type: (string) Specify the data type in which the block data is
returned. Supported values are ``dict`` and ``list``. The default value is
``dict``.
* student_view_data: (list) Specify the types of blocks for which to return
the ``student_view_data`` response value, which consists of a JSON
representation of the block's data. Example: ``student_view_data=video``.
* 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``.
.. _Blocks Response Values:
=====================
Response Values
=====================
The following fields are returned with a successful response.
* root: The ID of the root node of the requested course block structure.
* blocks: A dictionary or list, based on the value of the ``return_type``
query parameter. Maps block usage IDs to a collection of information about
each block, as described in the following fields.
* id: (string) The usage ID of the block.
* type: (string) The type of block. Values are 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.
* children: (list) If the block has child blocks, an ordered list of IDs of
the child blocks. Returned only if ``children`` is included in the
``requested_fields`` query parameter.
* block_counts: (dict) For each block type specified in the ``block_counts``
query parameter, the aggregate number of blocks of that type within the
root block and all of its descendants. For example, if you specify
``block_counts=video,problem`` as a query parameter, in the
``block_counts`` response value the number of video blocks and problem
blocks in the specified block and in its children, is returned.
* graded: (boolean) Whether or not the block or any of its descendants is
graded. Returned only if ``graded`` is included in the ``requested_fields``
query parameter.
* format: (string) The assignment type of the block. Possible values can be
``Homework``, ``Lab``, ``Midterm Exam``, and ``Final Exam``. Returned only if
``format`` is included in the ``requested_fields`` query parameter.
* student_view_data: (dict) The JSON data for this block, if the specified
block type implements the ``student_view_data`` method. The JSON data can
be used to natively render the XBlock. Returned only if the
``student_view_data`` query parameter contains this block's type. See also
``student_view_multi_device`` and ``student_view_url``.
* student_view_multi_device: (boolean) This value indicates whether or not
the HTML of the student view that is rendered at the ``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`` query parameter.
* student_view_url: (string) The URL to retrieve the HTML rendering of the
block's student view. The HTML can include CSS and Javascript code. This
field can be used in combination with the ``student_view_multi_device``
field to determine whether a block can be viewed on a device. This URL can
be used as a fallback if the ``student_view_data`` for this block type is
not supported by the client or by the block.
* lms_web_url: (string) The URL to the navigational container of the XBlock
on the web LMS. This URL can be used as a fallback if the
``student_view_data`` and ``student_view_url`` fields are not supported.
* lti_url: (string) The block URL for an LTI consumer. Returned only if the
``ENABLE_LTI_PROVIDER`` Django setting is set to ``True``.
============================================================================
Example Response Showing a List of Course Blocks in a Specified Course
============================================================================
The following example response is returned from this request:
GET /api/courses/v1/blocks/?course_id=edX/DemoX/Demo_Course&all_blocks=true
&block_counts=video,html,problem&requested_fields=graded,format,student_view_data,
student_view_url,student_view_multi_device&student_view_data=video,html,problem
Only the top level block in the course is returned, because the ``depth``
parameter was not specified.
.. code-block:: json
{
"root": "i4x://edX/DemoX/course/Demo_Course",
"blocks": {
"i4x://edX/DemoX/course/Demo_Course": {
"display_name": "edX Demonstration Course",
"graded": false,
"student_view_url": "https://courses.edx.org/xblock/i4x://edX/DemoX/
course/Demo_Course",
"student_view_multi_device": false,
"lms_web_url": "https://courses.edx.org/courses/edX/DemoX/Demo_Course/
jump_to/i4x://edX/DemoX/ course/Demo_Course",
"type": "course",
"id": "i4x://edX/DemoX/course/Demo_Course",
"block_counts": {
"problem": 23,
"html": 32,
"video": 5
}
}
}
}
.. _Get a list of the course blocks in a block tree:
*********************************************
Get a List of Course Blocks in a Block Tree
*********************************************
The endpoint to get a list of course blocks in a specified block tree is
``/api/courses/v1/blocks/{usage_id}/``.
=====================
Use Case
=====================
Get a list of course blocks in a specified block tree. Response results depend
on the specified user's permissions level within a course, as well as group
membership and individual allowances (such as due date extensions), if any.
=====================
Request Format
=====================
GET /api/courses/v1/blocks/{usage_id}/
Example:
GET /api/courses/v1/blocks/i4x%3A%2F%2FedX%2FDemoX%2Fvertical
%2F2152d4a4aadc4cb0af5256394a3d1fc7?all_blocks=true
=====================
Query Parameters
=====================
:ref:`Query parameters<Blocks Query Parameters>` for this endpoint are the
same as those for :ref:`Get a list of the course blocks in a course`.
=====================
Response Values
=====================
:ref:`Response values<Blocks Response Values>` for this endpoint are the same
as those for :ref:`Get a list of the course blocks in a course`.
================================================================
Example Response Showing a List of Course Blocks in a Block Tree
================================================================
The following example response is returned from this request:
GET /api/courses/v1/blocks/i4x%3A%2F%2FedX%2FDemoX%2Fvertical
%2F2152d4a4aadc4cb0af5256394a3d1fc7?all_blocks=true
.. code-block:: json
{
"root": "i4x://edX/DemoX/vertical/2152d4a4aadc4cb0af5256394a3d1fc7",
"blocks": {
"i4x://edX/DemoX/discussion/e5eac7e1a5a24f5fa7ed77bb6d136591": {
"display_name": "",
"lms_web_url": "https://courses.edx.org/courses/edX/DemoX/Demo_Course/
jump_to/i4x://edX/DemoX/discussion/e5eac7e1a5a24f5fa7ed77bb6d136591",
"type": "discussion",
"id": "i4x://edX/DemoX/discussion/e5eac7e1a5a24f5fa7ed77bb6d136591",
"student_view_url": "https://courses.edx.org/xblock/i4x://edX/DemoX/
discussion/e5eac7e1a5a24f5fa7ed77bb6d136591"
},
"i4x://edX/DemoX/vertical/2152d4a4aadc4cb0af5256394a3d1fc7": {
"display_name": "Pointing on a Picture",
"lms_web_url": "https://courses.edx.org/courses/edX/DemoX/Demo_Course/
jump_to/i4x://edX/DemoX/vertical/2152d4a4aadc4cb0af5256394a3d1fc7",
"type": "vertical",
"id": "i4x://edX/DemoX/vertical/2152d4a4aadc4cb0af5256394a3d1fc7",
"student_view_url": "https://courses.edx.org/xblock/i4x://edX/DemoX/
vertical/2152d4a4aadc4cb0af5256394a3d1fc7"
},
"i4x://edX/DemoX/problem/c554538a57664fac80783b99d9d6da7c": {
"display_name": "Pointing on a Picture",
"lms_web_url": "https://courses.edx.org/courses/edX/DemoX/Demo_Course/
jump_to/i4x://edX/DemoX/problem/c554538a57664fac80783b99d9d6da7c",
"type": "problem",
"id": "i4x://edX/DemoX/problem/c554538a57664fac80783b99d9d6da7c",
"student_view_url": "https://courses.edx.org/xblock/i4x://edX/DemoX/
problem/c554538a57664fac80783b99d9d6da7c"
}
}
}

226
docs/en_us/platform_api/source/courses/courses.rst Normal file
View File

@@ -0,0 +1,226 @@
.. _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>"
}

14
docs/en_us/platform_api/source/courses/index.rst Normal file
View File

@@ -0,0 +1,14 @@
.. _edX Platform Courses API:
#####################################
Courses API Version 1.0
#####################################
.. toctree::
:maxdepth: 2
overview
courses
blocks

65
docs/en_us/platform_api/source/courses/overview.rst Normal file
View File

@@ -0,0 +1,65 @@
.. _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}

1
docs/en_us/platform_api/source/index.rst
View File

@@ -24,6 +24,7 @@ Supported APIs
.. toctree::
:maxdepth: 2
courses/index
enrollment/index
user/index

1
docs/en_us/platform_api/source/overview.rst
View File

@@ -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`

45
lms/djangoapps/course_api/blocks/views.py
View File

@@ -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

18
lms/djangoapps/course_api/views.py
View File

@@ -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:**