From a1394e9945c06ff4b68ee8faddd979bc71c9c746 Mon Sep 17 00:00:00 2001 From: Carol Tong Date: Fri, 29 Apr 2016 13:23:02 -0400 Subject: [PATCH] Add documentation for Courses API --- .../platform_api/source/courses/blocks.rst | 290 ++++++++++++++++++ .../platform_api/source/courses/courses.rst | 226 ++++++++++++++ .../platform_api/source/courses/index.rst | 14 + .../platform_api/source/courses/overview.rst | 65 ++++ docs/en_us/platform_api/source/index.rst | 1 + docs/en_us/platform_api/source/overview.rst | 1 + lms/djangoapps/course_api/blocks/views.py | 45 ++- lms/djangoapps/course_api/views.py | 18 +- 8 files changed, 636 insertions(+), 24 deletions(-) create mode 100644 docs/en_us/platform_api/source/courses/blocks.rst create mode 100644 docs/en_us/platform_api/source/courses/courses.rst create mode 100644 docs/en_us/platform_api/source/courses/index.rst create mode 100644 docs/en_us/platform_api/source/courses/overview.rst diff --git a/docs/en_us/platform_api/source/courses/blocks.rst b/docs/en_us/platform_api/source/courses/blocks.rst new file mode 100644 index 0000000000..6ee8fe5d52 --- /dev/null +++ b/docs/en_us/platform_api/source/courses/blocks.rst @@ -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= + +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` 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` 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" + } + } + } diff --git a/docs/en_us/platform_api/source/courses/courses.rst b/docs/en_us/platform_api/source/courses/courses.rst new file mode 100644 index 0000000000..413ba5c043 --- /dev/null +++ b/docs/en_us/platform_api/source/courses/courses.rst @@ -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` 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": "

Include your long course description here.

" + } diff --git a/docs/en_us/platform_api/source/courses/index.rst b/docs/en_us/platform_api/source/courses/index.rst new file mode 100644 index 0000000000..fe7d75b43b --- /dev/null +++ b/docs/en_us/platform_api/source/courses/index.rst @@ -0,0 +1,14 @@ +.. _edX Platform Courses API: + +##################################### +Courses API Version 1.0 +##################################### + +.. toctree:: + :maxdepth: 2 + + overview + courses + blocks + + diff --git a/docs/en_us/platform_api/source/courses/overview.rst b/docs/en_us/platform_api/source/courses/overview.rst new file mode 100644 index 0000000000..36433cb027 --- /dev/null +++ b/docs/en_us/platform_api/source/courses/overview.rst @@ -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` and +:ref:`Blocks` 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} diff --git a/docs/en_us/platform_api/source/index.rst b/docs/en_us/platform_api/source/index.rst index 4e9d2b1199..0f74557ba8 100644 --- a/docs/en_us/platform_api/source/index.rst +++ b/docs/en_us/platform_api/source/index.rst @@ -24,6 +24,7 @@ Supported APIs .. toctree:: :maxdepth: 2 + courses/index enrollment/index user/index diff --git a/docs/en_us/platform_api/source/overview.rst b/docs/en_us/platform_api/source/overview.rst index ff883127ab..99842c0cfb 100644 --- a/docs/en_us/platform_api/source/overview.rst +++ b/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` diff --git a/lms/djangoapps/course_api/blocks/views.py b/lms/djangoapps/course_api/blocks/views.py index f6e73ed928..e8572322aa 100644 --- a/lms/djangoapps/course_api/blocks/views.py +++ b/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 diff --git a/lms/djangoapps/course_api/views.py b/lms/djangoapps/course_api/views.py index f2c09d1874..33aea96e29 100644 --- a/lms/djangoapps/course_api/views.py +++ b/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:**