diff --git a/docs/en_us/platform_api/source/authentication.rst b/docs/en_us/platform_api/source/authentication.rst index 1ee2520fb5..a650658ba8 100644 --- a/docs/en_us/platform_api/source/authentication.rst +++ b/docs/en_us/platform_api/source/authentication.rst @@ -1,23 +1,23 @@ .. _edX API Authentication: ############################# -edX API Authentication +EdX API Authentication ############################# - ************* OAuth 2.0 ************* -The edX Platform API uses OAuth 2.0 for authentication. OAuth 2.0 is an open +The edX Platform APIs use OAuth 2.0 for authentication. OAuth 2.0 is an open standard used by many systems that require secure user authentication. See the `OAuth 2.0 Standard`_ standard for more information. - *************************************** Registering with Your Open edX Instance *************************************** -To use the edX Platform API with courses on you instance of Open edX, you must register your application with the Open edX server. See the OAuth 2.0 specification for details. +To use the edX Platform API with courses on your instance of Open edX, you must +register your application with the Open edX server. See the OAuth 2.0 +specification for details. .. include:: links.rst \ No newline at end of file diff --git a/docs/en_us/platform_api/source/change_log.rst b/docs/en_us/platform_api/source/change_log.rst index 87ca5f97c8..e2bd75451a 100644 --- a/docs/en_us/platform_api/source/change_log.rst +++ b/docs/en_us/platform_api/source/change_log.rst @@ -3,7 +3,7 @@ Change Log ############ ***************** -January, 2015 +2015 ***************** .. list-table:: @@ -12,5 +12,9 @@ January, 2015 * - Date - Change + * - 2 April 2015 + - Added the :ref:`EdX Platform Course Structure API Version 0`, :ref:`edX + Platform Enrollment API Version 1.0` and :ref:`edX Platform User API + Version 0` sections. * - 29 January 2015 - Added the :ref:`Get or Change User Status in a Course` section. diff --git a/docs/en_us/platform_api/source/conf.py b/docs/en_us/platform_api/source/conf.py index 41df4a3c25..3b89f8b45e 100644 --- a/docs/en_us/platform_api/source/conf.py +++ b/docs/en_us/platform_api/source/conf.py @@ -40,10 +40,141 @@ MOCK_MODULES = [ 'opaque_keys.edx.locator', 'LibraryLocator', 'Location', + 'ipware', + 'ip', + 'ipware.ip', + 'get_ip', + 'pygeoip', + 'ipaddr', + 'django_countries', + 'fields', + 'django_countries.fields', + 'opaque_keys', + 'opaque_keys.edx', + 'opaque_keys.edx.keys', + 'CourseKey', + 'UsageKey', + 'BlockTypeKey', + 'opaque_keys.edx.locations', + 'SlashSeparatedCourseKey', + 'Locator', + 'south', + 'modelsinspector', + 'south.modelsinspector', + 'add_introspection_rules', + 'courseware', + 'access', + 'courseware.access', + 'is_mobile_available_for_user', + 'courseware.model_data', + 'courseware.module_render', + 'courseware.views', + 'util.request', + 'eventtracking', + 'xmodule', + 'xmodule.exceptions', + 'xmodule.modulestore', + 'xmodule.modulestore.exceptions', + 'xmodule.modulestore.django', + 'courseware.models', + 'milestones', + 'milestones.api', + 'milestones.models', + 'milestones.exceptions', + 'ratelimitbackend', + 'analytics', + 'courseware.courses', + 'staticfiles', + 'storage', + 'staticfiles.storage', + 'content', + 'xmodule.contentstore', + 'xmodule.contentstore.content', + 'xblock.exceptions', + 'xmodule.seq_module', + 'xmodule.vertical_module', + 'xmodule.x_module', + 'nltk', + 'ratelimitbackend', + 'ratelimitbackend.exceptions', + 'social', + 'social.apps', + 'social.apps.django_app', + 'social.backends', + 'mako', + 'exceptions', + 'mako.exceptions', + 'boto', + 'exception', + 'boto.exception', + 'PIL', + 'reportlab', + 'lib', + 'reportlab.lib', + 'pdfgen', + 'canvas', + 'pdfgen', + 'pdfgen.canvas', + 'reportlab.pdfgen', + 'reportlab.pdfgen.canvas', + 'reportlab.lib.pagesizes', + 'reportlab.lib.units', + 'reportlab.lib.styles', + 'reportlab.platypus', + 'reportlab.platypus.tables', + 'boto', + 's3', + 'connection', + 'boto.s3', + 'boto.s3.connection', + 'boto.s3.key', + 'Crypto', + 'Crypto.Cipher', + 'Crypto.PublicKey', + 'openid', + 'store', + 'interface', + 'openid.store', + 'store.interface', + 'openid.store.interface', + 'external_auth.views', + 'html_to_text', + 'mail_utils', + 'ratelimitbackend.backends', + 'social.apps.django_app.default', + 'social.exceptions', + 'social.pipeline', + 'xmodule.error_module', + 'accounts.api', + 'modulestore.mongo.base', + 'xmodule.modulestore.mongo', + 'xmodule.modulestore.mongo.base', + 'edxval', + 'edxval.api', + 'model_utils', + 'model_utils.models', + 'model_utils.managers', + 'certificates', + 'certificates.models', + 'certificates.models.GeneratedCertificate', + 'shoppingcart', + 'shopppingcart.models', + 'shopppingcart.api', + 'api', + 'student', + 'student.views', + 'student.forms', + 'student.models', + 'celery', + 'celery.task', + 'student.roles', + 'embargo.models', + 'xmodule.vertical_block', + 'vertical_block' ] for mod_name in MOCK_MODULES: - sys.modules[mod_name] = mock.Mock() + sys.modules[mod_name] = mock.Mock(class_that_is_extended=object) on_rtd = os.environ.get('READTHEDOCS', None) == 'True' @@ -73,11 +204,9 @@ if not on_rtd: # only import and set the theme if we're building docs locally root = path('../../../..').abspath() sys.path.insert(0, root) sys.path.append(root / "common/lib/xmodule") +sys.path.append(root / "common/djangoapps") sys.path.append(root / "lms/djangoapps") -sys.path.append(root / "lms/djangoapps/mobile_api") -sys.path.append(root / "lms/djangoapps/mobile_api/course_info") -sys.path.append(root / "lms/djangoapps/mobile_api/users") -sys.path.append(root / "lms/djangoapps/mobile_api/video_outlines") +sys.path.append(root / "openedx/core/djangoapps") sys.path.insert( 0, @@ -105,7 +234,7 @@ extensions = [ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon'] -project = u'edX Platform API Version 0.5 Alpha' +project = u'EdX Platform APIs' copyright = u'2015, edX' exclude_patterns = ['build', 'links.rst'] diff --git a/docs/en_us/platform_api/source/course_structure/course_structure.rst b/docs/en_us/platform_api/source/course_structure/course_structure.rst new file mode 100644 index 0000000000..97bb8a80c3 --- /dev/null +++ b/docs/en_us/platform_api/source/course_structure/course_structure.rst @@ -0,0 +1,193 @@ +######################################## +Course Structure API Module +######################################## + +This page contains information on using the Course Structure API to +complete these actions: + +* :ref:`Get a list of courses in the edX platform ` + +* :ref:`Get details about a course ` + +* :ref:`Get a course's structure, or blocks ` + +* :ref:`Get a courses grading policy ` + +.. _Get a List of Courses: + +************************** +Get a List of Courses +************************** + +.. autoclass:: course_structure_api.v0.views.CourseList + +**Example response** + +.. code-block:: json + + { + "count": 809, + "next": "https://courses.edx.org/api/course_structure/v0/courses/?page=3", + "previous": "https://courses.edx.org/api/course_structure/v0/courses/?page=1", + "num_pages": 81, + "results": [ + { + "id": "ANUx/ANU-ASTRO1x/1T2014", + "name": "Greatest Unsolved Mysteries of the Universe", + "category": "course", + "org": "ANUx", + "run": "1T2014", + "course": "ANU-ASTRO1x", + "uri": "https://courses.edx.org/api/course_structure/v0/courses/ANUx/ANU-ASTRO1x/1T2014/", + "image_url": "/c4x/ANUx/ANU-ASTRO1x/asset/dome_dashboard.jpg", + "start": "2014-03-24T18:30:00Z", + "end": null + }, + { + "id": "ANUx/ANU-ASTRO4x/1T2015", + "name": "COSMOLOGY", + "category": "course", + "org": "ANUx", + "run": "1T2015", + "course": "ANU-ASTRO4x", + "uri": "https://courses.edx.org/api/course_structure/v0/courses/ANUx/ANU-ASTRO4x/1T2015/", + "image_url": "/c4x/ANUx/ANU-ASTRO4x/asset/ASTRO4x_dashboard_image.jpeg", + "start": "2015-02-03T00:00:00Z", + "end": "2015-04-28T23:30:00Z" + } + . . . + ] + } +.. _Get Course Details: + +************************** +Get Course Details +************************** + +.. autoclass:: course_structure_api.v0.views.CourseDetail + +**Example response** + +.. code-block:: json + + HTTP 200 OK + Vary: Accept + Content-Type: text/html; charset=utf-8 + Allow: GET, HEAD, OPTIONS + + { + "id": "ANUx/ANU-INDIA1x/1T2014", + "name": "Engaging India", + "category": "course", + "org": "ANUx", + "run": "1T2014", + "course": "ANU-INDIA1x", + "uri": "https://courses.edx.org/api/course_structure/v0/courses/ANUx/ANU-INDIA1x/1T2014/", + "image_url": "/c4x/ANUx/ANU-INDIA1x/asset/homepage_course_image.jpg", + "start": "2014-04-29T01:00:00Z", + "end": "2014-07-21T01:00:00Z" + } + +.. _Get the Course Structure: + +************************** +Get the Course Structure +************************** + +.. autoclass:: course_structure_api.v0.views.CourseStructure + +**Example response** + +.. code-block:: json + + { + "root": "i4x://ANUx/ANU-INDIA1x/course/1T2014", + "blocks": { + "i4x://ANUx/ANU-INDIA1x/html/834f845ae8b944f1882f14ce6417c9d1": { + "id": "i4x://ANUx/ANU- + INDIA1x/html/834f845ae8b944f1882f14ce6417c9d1", + "type": "html", + "display_name": "", + "graded": false, + "format": null, + "children": [] + }, + "i4x://ANUx/ANU-INDIA1x/html/c3493aaebaba4ab6a0499fbc27ac3b0e": { + "id": "i4x://ANUx/ANU- + INDIA1x/html/c3493aaebaba4ab6a0499fbc27ac3b0e", + "type": "problem", + "display_name": "Check your learning - Part 1", + "graded": true, + "format": null, + "children": [] + }, + "i4x://ANUx/ANU-INDIA1x/sequential/3731eee6a39c473c98ef6a5c3f56c04c": { + "id": "i4x://ANUx/ANU- + INDIA1x/sequential/3731eee6a39c473c98ef6a5c3f56c04c", + "type": "sequential", + "display_name": "Reflective project", + "graded": true, + "format": "Reflective Project", + "children": [ + "i4x://ANUx/ANU- + INDIA1x/vertical/efe3f47a5bc24894b726c229d6bf5968", + "i4x://ANUx/ANU- + INDIA1x/vertical/9106a1b1fad040858bad56fe5d48074e", + "i4x://ANUx/ANU- + INDIA1x/vertical/27d2cf635bd44038a1207461b761a63a", + "i4x://ANUx/ANU- + INDIA1x/vertical/94b719b765b046e2a811f1c4e4f84e5b" + ] + }, + "i4x://ANUx/ANU-INDIA1x/vertical/0a3cd583cb1d4108bfbdaf57c511da3a": { + "id": "i4x://ANUx/ANU- + INDIA1x/vertical/0a3cd583cb1d4108bfbdaf57c511da3a", + "type": "vertical", + "display_name": "What you need to do this week", + "graded": false, + "format": null, + "children": [ + "i4x://ANUx/ANU-INDIA1x/html/a20abbba4a0f4a578d96cbdd4b34307b" + ] + }, + . . . + } + +.. _Get the Course Grading Policy: + +***************************** +Get the Course Grading Policy +***************************** + +.. autoclass:: course_structure_api.v0.views.CourseGradingPolicy + +**Example response** + +.. code-block:: json + + HTTP 200 OK + Vary: Accept + Content-Type: text/html; charset=utf-8 + Allow: GET, HEAD, OPTIONS + + [ + { + "assignment_type": "Week 1 Survey", + "count": 2, + "dropped": 1, + "weight": 0.03 + }, + { + "assignment_type": "Week 5 Survey", + "count": 2, + "dropped": 1, + "weight": 0.03 + }, + { + "assignment_type": "Reflective Project", + "count": 1, + "dropped": 0, + "weight": 0.2 + }, + . . . + ] diff --git a/docs/en_us/platform_api/source/course_structure/endpoints.rst b/docs/en_us/platform_api/source/course_structure/endpoints.rst new file mode 100644 index 0000000000..fa96bc08dd --- /dev/null +++ b/docs/en_us/platform_api/source/course_structure/endpoints.rst @@ -0,0 +1,27 @@ +.. _EdX Platform Course Structure API Endpoints: + +################################################ +Course Structure API Endpoints +################################################ + +You use the Course Structure API to view information about +courses. + +The following tasks and endpoints are currently supported. + + +.. list-table:: + :widths: 10 70 + :header-rows: 1 + + * - To: + - Use this endpoint: + * - :ref:`Get a list of courses in the edX platform ` + - GET /api/course_structure/v0/courses/ + * - :ref:`Get details about a course ` + - GET /api/course_structure/v0/courses/{course_id}/ + * - :ref:`Get a course's structure, or blocks ` + - GET /api/course_structure/v0/course_structures/{course_id}/ + * - :ref:`Get a course's grading policy ` + - GET /api/course_structure/v0/grading_policies/{course_id}/ + \ No newline at end of file diff --git a/docs/en_us/platform_api/source/course_structure/index.rst b/docs/en_us/platform_api/source/course_structure/index.rst new file mode 100644 index 0000000000..0aa08224af --- /dev/null +++ b/docs/en_us/platform_api/source/course_structure/index.rst @@ -0,0 +1,12 @@ +.. _EdX Platform Course Structure API Version 0: + +############################################# +Course Structure API Version 0 +############################################# + +.. toctree:: + :maxdepth: 2 + + overview + endpoints + course_structure diff --git a/docs/en_us/platform_api/source/course_structure/overview.rst b/docs/en_us/platform_api/source/course_structure/overview.rst new file mode 100644 index 0000000000..099f362359 --- /dev/null +++ b/docs/en_us/platform_api/source/course_structure/overview.rst @@ -0,0 +1,31 @@ +.. _EdX Platform Course Structure API Overview: + +################################################ +Course Structure API Overview +################################################ + +Use the edX Platform Course Structure API to view course details, including the +blocks in the course and the course grading policy. + +******************************************** +Course Structure API Version 0 +******************************************** + +The Course Structure API is currently at version 0. We plan on making +significant enhancements to this API. Currently the Course Structure API is for +internal use only; third parties cannot use the API to access course structure +data. + +*********************************************** +Course Structure API Capabilities +*********************************************** + +With the Course Structure API, you can complete these tasks. + +* :ref:`Get a list of courses in the edX platform ` + +* :ref:`Get details about a course ` + +* :ref:`Get a course's structure, or blocks ` + +* :ref:`Get a course's grading policy ` diff --git a/docs/en_us/platform_api/source/enrollment/endpoints.rst b/docs/en_us/platform_api/source/enrollment/endpoints.rst new file mode 100644 index 0000000000..377d1be4db --- /dev/null +++ b/docs/en_us/platform_api/source/enrollment/endpoints.rst @@ -0,0 +1,26 @@ +.. _edX Enrollment API Endpoints: + +################################################ +Enrollment API Endpoints +################################################ + +You use the Enrollment API to view information about users and +their course enrollments, course information, and videos and transcripts. + +The following tasks and endpoints are currently supported. + + +.. list-table:: + :widths: 10 70 + :header-rows: 1 + + * - To: + - Use this endpoint: + * - :ref:`Get the user's enrollment status in a course ` + - /api/enrollment/v1/enrollment/{user_id},{course_id} + * - :ref:`Get enrollment details for a course` + - /api/enrollment/v1/course/{course_id} + * - :ref:`View a user's enrollments ` + - /api/enrollment/v1/enrollment + * - :ref:`Enroll a user in a course ` + - /api/enrollment/v1/enrollment{“course_details”:{“course_id”:“*course_id*”}} \ No newline at end of file diff --git a/docs/en_us/platform_api/source/enrollment/enrollment.rst b/docs/en_us/platform_api/source/enrollment/enrollment.rst new file mode 100644 index 0000000000..504b455e06 --- /dev/null +++ b/docs/en_us/platform_api/source/enrollment/enrollment.rst @@ -0,0 +1,167 @@ +################################################## +Enrollment API Module +################################################## + +This page contains information on using the Enrollment API to complete +these actions: + +* :ref:`Get the user's enrollment status in a course ` +* :ref:`Get enrollment details for a course` +* :ref:`View a user's enrollments ` +* :ref:`Enroll a user in a course ` + + +.. _Get the Users Enrollment Status in a Course: + +******************************************** +Get the User's Enrollment Status in a Course +******************************************** + +.. autoclass:: enrollment.views.EnrollmentView + +**Example response showing the user's enrollment status in a course** + +.. code-block:: json + + HTTP 200 OK + Content-Type: application/json + Vary: Accept + Allow: GET, HEAD, OPTIONS + + { + "created": "2014-11-19T04:06:55Z", + "mode": "honor", + "is_active": true, + "course_details": { + "course_id": "edX/DemoX/Demo_Course", + "enrollment_end": null, + "course_modes": [ + { + "slug": "honor", + "name": "Honor Code Certificate", + "min_price": 0, + "suggested_prices": [], + "currency": "usd", + "expiration_datetime": null, + "description": null + } + ], + "enrollment_start": null, + "invite_only": false + }, + "user": "staff" + } + +.. _Get Enrollment Details for a Course: + +************************************ +Get Enrollment Details for a Course +************************************ + +.. autoclass:: enrollment.views.EnrollmentCourseDetailView + +**Example response showing a user's course enrollments** + +.. code-block:: json + + HTTP 200 OK + Content-Type: application/json + Vary: Accept + Allow: GET, HEAD, OPTIONS + + { + "course_id": "edX/DemoX/Demo_Course", + "enrollment_end": null, + "course_modes": [ + { + "slug": "honor", + "name": "Honor Code Certificate", + "min_price": 0, + "suggested_prices": [], + "currency": "usd", + "expiration_datetime": null, + "description": null + } + ], + "enrollment_start": null, + "invite_only": false + } + + +.. _View and add to a Users Course Enrollments: + +********************************************* +View and Add to a User's Course Enrollments +********************************************* + +.. autoclass:: enrollment.views.EnrollmentListView + + +**Example response showing a user's course enrollments** + +.. code-block:: json + + HTTP 200 OK + Content-Type: application/json + Vary: Accept + Allow: GET, POST, HEAD, OPTIONS + + [ + { + "created": "2014-09-19T18:08:37Z", + "mode": "honor", + "is_active": true, + "course_details": { + "course_id": "edX/DemoX/Demo_Course", + "enrollment_end": null, + "course_modes": [ + { + "slug": "honor", + "name": "Honor Code Certificate", + "min_price": 0, + "suggested_prices": [], + "currency": "usd", + "expiration_datetime": null, + "description": null + } + ], + "enrollment_start": null, + "invite_only": false + }, + "user": "honor" + }, + { + "created": "2014-09-19T18:09:35Z", + "mode": "honor", + "is_active": true, + "course_details": { + "course_id": "ArbisoftX/BulkyEmail101/2014-15", + "enrollment_end": null, + "course_modes": [ + { + "slug": "honor", + "name": "Honor Code Certificate", + "min_price": 0, + "suggested_prices": [], + "currency": "usd", + "expiration_datetime": null, + "description": null + } + ], + "enrollment_start": "2014-05-01T04:00:00Z", + "invite_only": false + }, + "user": "honor" + } + ] + + +**Example post request to enroll the user in a new course** + +.. code-block:: json + + { + “course_details”: { + “course_id”: “edX/DemoX/Demo_Course” + } + } \ No newline at end of file diff --git a/docs/en_us/platform_api/source/enrollment/index.rst b/docs/en_us/platform_api/source/enrollment/index.rst new file mode 100644 index 0000000000..2bf03fdb5c --- /dev/null +++ b/docs/en_us/platform_api/source/enrollment/index.rst @@ -0,0 +1,12 @@ +.. _edX Platform Enrollment API Version 1.0: + +######################################## +Enrollment API Version 1.0 +######################################## + +.. toctree:: + :maxdepth: 2 + + overview + endpoints + enrollment diff --git a/docs/en_us/platform_api/source/enrollment/overview.rst b/docs/en_us/platform_api/source/enrollment/overview.rst new file mode 100644 index 0000000000..742c50aaa1 --- /dev/null +++ b/docs/en_us/platform_api/source/enrollment/overview.rst @@ -0,0 +1,34 @@ +.. _edX Enrollment API Overview: + +################################################ +Enrollment API Overview +################################################ + +Use the Enrollment API to view user and course enrollment +information, and to enroll a user in a course. + +You can use the Enrollment API for web, desktop, and mobile +applications. + +**************************************** +Enrollment API Version 1.0 +**************************************** + +The Enrollment API is currently at version 1.0. We plan on making +significant enhancements to this API. + +******************************************** +Enrollment API Capabilities +******************************************** + +With the Enrollment API, you can complete these tasks. + +* :ref:`Get the user's enrollment status in a course ` + +* :ref:`Get enrollment details for a course` + +* :ref:`View a user's enrollments ` + +* :ref:`Enroll a user in a course ` diff --git a/docs/en_us/platform_api/source/index.rst b/docs/en_us/platform_api/source/index.rst index 33b3f583c0..2ff480c77e 100644 --- a/docs/en_us/platform_api/source/index.rst +++ b/docs/en_us/platform_api/source/index.rst @@ -1,15 +1,37 @@ -################################################ -edX Platform API Version 0.5 -################################################ +################## +EdX Platform APIs +################## + +.. toctree:: + :titlesonly: + + read_me + preface + change_log + +.. toctree:: + :maxdepth: 2 + + overview + authentication + +**************** +Supported APIs +**************** + +.. toctree:: + :maxdepth: 2 + + enrollment/index + mobile/index + +****************** +Experimental APIs +****************** .. toctree:: :maxdepth: 2 - read_me - preface - overview - authentication - endpoints - users - course_info - video_outlines + course_structure/index + user/index + diff --git a/docs/en_us/platform_api/source/course_info.rst b/docs/en_us/platform_api/source/mobile/course_info.rst similarity index 82% rename from docs/en_us/platform_api/source/course_info.rst rename to docs/en_us/platform_api/source/mobile/course_info.rst index 47c3d0c077..cd0af79f6e 100644 --- a/docs/en_us/platform_api/source/course_info.rst +++ b/docs/en_us/platform_api/source/mobile/course_info.rst @@ -1,10 +1,9 @@ ################################################## -Course Information API Module +Mobile Course Information API Module ################################################## -.. module:: mobile_api - -This page contains docstrings and example responses for: +This page describes how to use the Mobile Course Information API +to complete these actions: * `Get Course Updates`_ * `Get Course Handouts`_ @@ -17,28 +16,7 @@ This page contains docstrings and example responses for: Get Course Updates ******************* -.. .. autoclass:: course_info.views.CourseUpdatesList - -**Use Case** - -Get the content for course updates. - -**Example request**: - -``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates`` - -**Response Values** - -A array of course updates. Each course update contains: - -* date: The date of the course update. - -* content: The content, as a string, of the course update. HTML tags are not - included in the string. - -* status: Whether the update is visible or not. - -* id: The unique identifier of the update. +.. autoclass:: mobile_api.course_info.views.CourseUpdatesList **Example response** @@ -71,7 +49,7 @@ A array of course updates. Each course update contains: Get Course Handouts ******************* -.. .. autoclass:: course_info.views.CourseHandoutsList +.. autoclass:: mobile_api.course_info.views.CourseHandoutsList **Use Case** @@ -107,20 +85,7 @@ Get the HTML for course handouts. Get the Course About Page ************************** -.. .. autoclass:: course_info.views.CourseAboutDetail -.. :members: - -**Use Case** - -Get the HTML for the course about page. - -**Example request**: - -``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about`` - -**Response Values** - -* overview: The HTML for the course About page. +.. autoclass:: mobile_api.course_info.views.CourseAboutDetail **Example response** diff --git a/docs/en_us/platform_api/source/endpoints.rst b/docs/en_us/platform_api/source/mobile/endpoints.rst similarity index 87% rename from docs/en_us/platform_api/source/endpoints.rst rename to docs/en_us/platform_api/source/mobile/endpoints.rst index eaccadb28d..5c878cb4c7 100644 --- a/docs/en_us/platform_api/source/endpoints.rst +++ b/docs/en_us/platform_api/source/mobile/endpoints.rst @@ -1,14 +1,14 @@ -.. _edX Platform API Endpoints: +.. _edX PlatformMobile API Endpoints: ################################################ -edX LMS Platform Endpoints +Mobile API Endpoints ################################################ -The edX Platform API allows you to view information about users and their course enrollments, course information, and videos and transcripts. +You use the Mobile API enables to view information about users and +their course enrollments, course information, and videos and transcripts. The following tasks and endpoints are currently supported. - .. list-table:: :widths: 10 70 :header-rows: 1 diff --git a/docs/en_us/platform_api/source/mobile/index.rst b/docs/en_us/platform_api/source/mobile/index.rst new file mode 100644 index 0000000000..ff4f8c8767 --- /dev/null +++ b/docs/en_us/platform_api/source/mobile/index.rst @@ -0,0 +1,14 @@ +.. _edX Platform Mobile API Version 0.5: + +##################################### +Mobile API Version 0.5 +##################################### + +.. toctree:: + :maxdepth: 2 + + overview + endpoints + users + course_info + video_outlines diff --git a/docs/en_us/platform_api/source/mobile/overview.rst b/docs/en_us/platform_api/source/mobile/overview.rst new file mode 100644 index 0000000000..845bd6a993 --- /dev/null +++ b/docs/en_us/platform_api/source/mobile/overview.rst @@ -0,0 +1,40 @@ +.. _edX Platform Mobile API Overview: + +################################################ +Mobile API Overview +################################################ + +Use the eMobile API to build mobile applications for students to +view course information and videos for courses on your instance of Open edX. + +****************************************** +Mobile API Version 0.5, Alpha +****************************************** + +The Mobile API is currently at version 0.5 and is an Alpha +release. We plan on making significant enhancements and changes to the API. + +.. caution:: + As this is a new and rapidly evolving API, at this time edX does not guarantee + forward compatibility. We encourage you to use and experiment with the API, + while keeping in mind that endpoints might change. + +************************************* +Mobile API Capabilities +************************************* + +With the Mobile API, you can complete these tasks. + +* Get :ref:`user details` and :ref:`course enrollments` for a user. + +* :ref:`Get or change user status in a course ` + +* Get :ref:`course information`, :ref:`updates`, and :ref:`handouts` for courses the + user is enrolled in. + +* Get :ref:`videos` and :ref:`transcripts` for courses the user is enrolled in. + \ No newline at end of file diff --git a/docs/en_us/platform_api/source/users.rst b/docs/en_us/platform_api/source/mobile/users.rst similarity index 54% rename from docs/en_us/platform_api/source/users.rst rename to docs/en_us/platform_api/source/mobile/users.rst index 97d5c0e8e7..fc2a7ddafe 100644 --- a/docs/en_us/platform_api/source/users.rst +++ b/docs/en_us/platform_api/source/mobile/users.rst @@ -1,10 +1,9 @@ -######################### -User API Module -######################### +#################################### +Mobile User API Module +#################################### -.. module:: mobile_api - -This page describes how to use the mobile user API to: +This page describes how to use the Mobile User API to complete +these actions: * `Get User Details`_ * `Get a User's Course Enrollments`_ @@ -16,35 +15,7 @@ This page describes how to use the mobile user API to: Get User Details ******************* -.. .. autoclass:: mobile_api.users.views.UserDetail -.. :members: - -**Use Case** - -Get information about the specified user and access other resources the user -has permissions for. - -Users are redirected to this endpoint after logging in. - -You can use the **course_enrollments** value in the response to get a list of -courses the user is enrolled in. - -**Example request** - -``GET /api/mobile/v0.5/users/{username}`` - -**Response Values** - -* id: The ID of the user. - -* username: The username of the currently logged in user. - -* email: The email address of the currently logged in user. - -* name: The full name of the currently logged in user. - -* course_enrollments: The URI to list the courses the currently logged in user - is enrolled in. +.. autoclass:: mobile_api.users.views.UserDetail **Example response** @@ -69,52 +40,7 @@ courses the user is enrolled in. Get a User's Course Enrollments ************************************** -.. .. autoclass:: users.views.UserCourseEnrollmentsList -.. :members: - -**Use Case** - -Get information about the courses the currently logged in user is enrolled in. - -**Example request**: - -``GET /api/mobile/v0.5/users/{username}/course_enrollments/`` - -**Response Values** - -* created: The date the course was created. - -* mode: The type of certificate registration for this course: honor or - certified. - -* is_active: Whether the course is currently active; true or false. - -* course: A collection of data about the course: - -* course_about: The URI to get the data for the course About page. - -* course_updates: The URI to get data for course updates. - -* number: The course number. - -* org: The organization that created the course. - -* video_outline: The URI to get the list of all vides the user can access in - the course. - -* id: The unique ID of the course. - -* latest_updates: Reserved for future use. - -* end: The end date of the course. - -* name: The name of the course. - -* course_handouts: The URI to get data for course handouts. - -* start: The data and time the course starts. - -* course_image: The path to the course image. +.. autoclass:: mobile_api.users.views.UserCourseEnrollmentsList **Example response** @@ -174,36 +100,7 @@ Get information about the courses the currently logged in user is enrolled in. Get or Change User Status in a Course ************************************** -.. .. autoclass:: mobile_api.users.views.UserCourseStatus -.. :members: - -**Use Case** - -Get or update the ID of the module that the specified user last visited in the -specified course. - -**Example request** - -``GET /api/mobile/v0.5/users/{username}/course_status_info/{course_id}`` - -.. code-block:: http - - PATCH /api/mobile/v0.5/users/{username}/course_status_info/{course_id} - body: - last_visited_module_id={module_id} - modification_date={date} - - The modification_date is optional. If it is present, the update will - only take effect if the modification_date is later than the - modification_date saved on the server. - -**Response Values** - -* last_visited_module_id: The ID of the last module visited by the user in the - course. - -* last_visited_module_path: The ID of the modules in the path from the last - visited module to the course module. +.. autoclass:: mobile_api.users.views.UserCourseStatus **Example Response** diff --git a/docs/en_us/platform_api/source/video_outlines.rst b/docs/en_us/platform_api/source/mobile/video_outlines.rst similarity index 51% rename from docs/en_us/platform_api/source/video_outlines.rst rename to docs/en_us/platform_api/source/mobile/video_outlines.rst index 4163662d47..1056a7af6d 100644 --- a/docs/en_us/platform_api/source/video_outlines.rst +++ b/docs/en_us/platform_api/source/mobile/video_outlines.rst @@ -1,10 +1,9 @@ ################################################## -Video Outlines API Module +Mobile Video Outlines API Module ################################################## -.. module:: mobile_api - -This page contains docstrings and example responses for: +This page describes how to use the Mobile Video Outlines API to +complete these actions: * `Get the Video List`_ * `Get a Video Transcript`_ @@ -15,57 +14,8 @@ This page contains docstrings and example responses for: Get the Video List ******************* -.. .. autoclass:: video_outlines.views.VideoSummaryList -.. :members: +.. autoclass:: mobile_api.video_outlines.views.VideoSummaryList -**Use Case** - -Get a list of all videos in the specified course. You can use the video_url -value to access the video file. - -**Example request**: - -``GET /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}`` - -**Response Values** - -An array of videos in the course. For each video: - -* section_url: The URL to the first page of the section that contains the video - in the Learning Managent System. - -* path: An array containing category and name values specifying the complete - path the the video in the courseware hierarcy. The following categories - values are included: "chapter", "sequential", and "vertical". The name value - is the display name for that object. - -* unit_url: The URL to the unit contains the video in the Learning Managent - System. - -* named_path: An array consisting of the display names of the courseware - objects in the path to the video. - -* summary: An array of data about the video that includes: - - * category: The type of component, in this case always "video". - - * video_thumbnail_url: The URL to the thumbnail image for the video, if - available. - - * language: The language code for the video. - - * name: The display name of the video. - - * video_url: The URL to the video file. Use this value to access the video. - - * duration: The length of the video, if available. - - * transcripts: An array of language codes and URLs to available video - transcripts. Use the URL value to access a transcript for the video. - - * id: The unique identifier for the video. - - * size: The size of the video file **Example response** @@ -120,16 +70,7 @@ An array of videos in the course. For each video: Get a Video Transcript *********************** -.. .. autoclass:: video_outlines.views.VideoTranscripts -.. :members: - -**Use Case** - -Use to get a transcript for a specified video and language. - -**Example request**: - -``/api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}`` +.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts **Response Values** diff --git a/docs/en_us/platform_api/source/overview.rst b/docs/en_us/platform_api/source/overview.rst index 8caf35b932..57e96de243 100644 --- a/docs/en_us/platform_api/source/overview.rst +++ b/docs/en_us/platform_api/source/overview.rst @@ -1,46 +1,29 @@ -.. _edX Platform API Overview: - ################################################ -edX Platform API Overview +Overview of the edX Platform APIs ################################################ -The edX Platform API enables you to build applications for students to view -course information and videos for courses on your instance of Open edX. +The edX Platform APIs are a rapidly growing and evolving set of capabilities +that enable you to build web, desktop, and mobile applications that work with +your Open edX instance. -The edX Platform API uses Representational State Transfer (REST) design -principles and supports JavaScript Object Notation (JSON) data-interchange -format. Our REST API is simple, lightweight and optimized. +The edX Platform APIs use REST design principles and support the JSON data- +interchange format. -You can use the edX Platform API for web, desktop, and mobile applications. +********************************************** +Supported edX Platform API Modules +********************************************** + +The following edX Platform APIs are currently supported: + +* :ref:`edX Platform Enrollment API Version 1.0` +* :ref:`edX Platform Mobile API Version 0.5` -************************************* -edX Platform API Version 0.5, Alpha -************************************* +********************************************** +Experimental edX Platform API Modules +********************************************** -The edX Platform API is currently at version 0.5 and is an Alpha release. We -plan on making significant enhancements and changes to the API. +The following edX Platform APIs are currently experimental: -.. caution:: - As this is a new and rapidly evolving API, at this time edX does not guarantee - forward compatibility. We encourage you to use and experiment with the API, - while keeping in mind that endpoints may change. - -****************************** -edX Platform API Capabilities -****************************** - -With the edX Platform API, you can: - -* Get :ref:`user details` and :ref:`course enrollments` for a user. - -* :ref:`Get or change user status in a course ` - -* Get :ref:`course information`, :ref:`updates`, and :ref:`handouts` for courses the - user is enrolled in. - -* Get :ref:`videos` and :ref:`transcripts` for courses the user is enrolled in. \ No newline at end of file +* :ref:`EdX Platform Course Structure API Version 0` +* :ref:`edX Platform User API Version 0` diff --git a/docs/en_us/platform_api/source/user/accounts.rst b/docs/en_us/platform_api/source/user/accounts.rst new file mode 100644 index 0000000000..ff2756073a --- /dev/null +++ b/docs/en_us/platform_api/source/user/accounts.rst @@ -0,0 +1,39 @@ +################################################## +User Accounts API Module +################################################## + +This page contains information on using the User Accounts API to +complete these actions: + +* `Get and Update the User's Account Information`_ + +.. _Get and Update the User's Account Information: + +********************************************** +Get and Update the User's Account Information +********************************************** + +.. autoclass:: user_api.accounts.views.AccountView + +**Example response showing the user's account information** + +.. code-block:: json + + HTTP 200 OK + Content-Type: application/json + Vary: Accept + Allow: GET, HEAD, OPTIONS, PATCH + + { + "username": "John", + "name": "John Doe", + "language": "", + "gender": "m", + "year_of_birth": 2007, + "level_of_education": "m", + "goals": "Professional Development", + "country": US, + "mailing_address": "406 Highland Ave., Somerville, MA 02144", + "email": "johndoe@company.com", + "date_joined": "2015-03-18T13:42:40Z" + } diff --git a/docs/en_us/platform_api/source/user/endpoints.rst b/docs/en_us/platform_api/source/user/endpoints.rst new file mode 100644 index 0000000000..a050796366 --- /dev/null +++ b/docs/en_us/platform_api/source/user/endpoints.rst @@ -0,0 +1,22 @@ +################################################ +User API Endpoints +################################################ + +You use the User API to view information about users and update +your own account. + +The following tasks and endpoints are currently supported. + +.. list-table:: + :widths: 10 70 + :header-rows: 1 + + * - To: + - Use this endpoint: + * - :ref:`Get a user's account information ` + - GET /api/user/v0/accounts/{username}/[?view=shared] + * - :ref:`Update your account information ` + - PATCH /api/user/v0/accounts/{username}/{“key”:”value”} “application + /merge-patch+json” diff --git a/docs/en_us/platform_api/source/user/index.rst b/docs/en_us/platform_api/source/user/index.rst new file mode 100644 index 0000000000..aa05686237 --- /dev/null +++ b/docs/en_us/platform_api/source/user/index.rst @@ -0,0 +1,12 @@ +.. _edX Platform User API Version 0: + +################################# +User API Version 0 +################################# + +.. toctree:: + :maxdepth: 2 + + overview + endpoints + accounts diff --git a/docs/en_us/platform_api/source/user/overview.rst b/docs/en_us/platform_api/source/user/overview.rst new file mode 100644 index 0000000000..b02dbf5a8e --- /dev/null +++ b/docs/en_us/platform_api/source/user/overview.rst @@ -0,0 +1,29 @@ +################################################ +User API Overview +################################################ + +Use the User API to view and update account information. + +You can use the User API for web, desktop, and mobile +applications. + +************************************* +EdX Platform User API Version 0 +************************************* + +The User API is currently at version 0. We plan on making +significant enhancements to this API. + +.. caution:: + As this is a new and rapidly evolving API, at this time edX does not guarantee + forward compatibility. We encourage you to use and experiment with the API, + while keeping in mind that endpoints might change. + +********************************************** +User API Capabilities +********************************************** + +With the User API, you can complete these tasks. + +* :ref:`Get and update the users' account information ` diff --git a/docs/en_us/shared/images/Announcement_subscriptions.png b/docs/en_us/shared/images/Announcement_subscriptions.png new file mode 100644 index 0000000000..80a6c63023 Binary files /dev/null and b/docs/en_us/shared/images/Announcement_subscriptions.png differ diff --git a/docs/en_us/shared/preface.rst b/docs/en_us/shared/preface.rst index 350ed5a0c5..d6e22f04f3 100644 --- a/docs/en_us/shared/preface.rst +++ b/docs/en_us/shared/preface.rst @@ -1,11 +1,11 @@ .. _Preface: -.. Doc team! Be sure that when you make any changes to this file that you also make them to the mirrored file in the edx-analytics-dashboard/docs repository. - Alison 19 Aug 14 - ############ Preface ############ +.. Doc team! Be sure that when you make any changes to this file that you also make them to the mirrored file in the edx-analytics-dashboard/docs repository. - Alison 19 Aug 14 + Course teams, researchers, developers, students: the edX community includes groups with a range of reasons for using the platform and objectives to accomplish. To help members of each group learn about what edX offers, reach @@ -13,14 +13,83 @@ goals, and solve problems, edX provides a variety of information resources. To help you find what you need, browse the edX offerings in these categories: -* :ref:`Resources for Course Teams` -* :ref:`Resources for Researchers` -* :ref:`Resources for Developers` -* :ref:`Resources for Students` +* `The edX Partner Portal`_ +* `The Open edX Portal`_ +* `Release Announcements through the Open edX Portal`_ +* `Resources for Course Teams`_ +* `Resources for Researchers`_ +* `Resources for Developers`_ +* `Resources for Students`_ All members of the edX community are encouraged to make use of any of the resources described in this preface. +.. _The edX Partner Portal: + +*********************** +The edX Partner Portal +*********************** + +The `edX Partner Portal`_ is the destination for partners to learn, connect, +and collaborate with one another. Partners can explore rich resources and share +success stories and best practices while staying up-to-date with important news +and updates. + +To use the edX Partner Portal, you must register and request verification as an +edX partner. If you are an edX partner and have not used the edX Partner +Portal, follow these steps. + +#. Visit `partners.edx.org`_, and select **Create New Account**. +#. Select **Request Partner Access**, then fill in your personal details. +#. Select **Create New Account**. You will receive a confirmation email with + your account access within 24 hours. + +.. _The Open edX Portal: + +*********************** +The Open edX Portal +*********************** + +The `Open edX Portal`_ is the destination for all edX users to learn about the +edX roadmap, as well as hosting, extending the edX platform, and contributing +to Open edX. In addition, the Open edX Portal provides product announcements, +the Open edX blog, and other rich community resources. + +All users can view content on the Open edX Portal without creating an account +and logging in. + +To comment on blog posts or the edX roadmap, you must create an account and log +in. If you do not have an account, follow these steps. + +#. Visit `open.edx.org/user/register`_. +#. Fill in your personal details. +#. Select **Create New Account**. You are then logged in to the `Open edX + Portal`_. + +*************************************************** +Release Announcements through the Open edX Portal +*************************************************** + +To receive and share product and release announcements by email, subscribe to +announcements on the `Open edX Portal`_. + +#. Create an account on the `Open edX Portal`_ as described above. +#. Go to https://open.edx.org/announcements. +#. Under **Announcement Type** in the **Subscriptions** block, select the type + of announcements that you want to receive through email. + + .. image:: ../../shared/images/Announcement_subscriptions.png + :alt: Subscription block in the Open edX Portal Announcements page. + +4. Click **Save**. + +You will now receive email messages when new announcements of the types you +selected are posted. + +.. note:: + EdX partners can complete the same steps on the **Announcements** page in the + `edX Partner Portal`_. + *********************** System Status *********************** @@ -42,6 +111,14 @@ Course teams include faculty, instructional designers, course staff, discussion moderators, and others who contribute to the creation and delivery of courses on edx.org or edX Edge. +edX101: Overview of Creating a Course +------------------------------------- + +The `edX101`_ course was built in Studio and is available for enrollment on +edx.org. This course takes one to two hours to complete, and is designed to +provide a high-level overview of the course creation and delivery process. It +also highlights the extensive capabilities of the edX platform. + Documentation ------------- @@ -65,7 +142,9 @@ Documentation for course teams is available on the docs.edx.org web page. peer- and self- evaluations of responses to a question. Note that this new feature is in limited release. -* `edX Open Learning XML Guide`_ provides guidelines for building edX courses with Open Learning XML (OLX). Note that this guide is currently an Alpha version. +* `edX Open Learning XML Guide`_ provides guidelines for building edX courses + with Open Learning XML (OLX). Note that this guide is currently an alpha + version. These guides open in your web browser. The left side of each page includes a **Search docs** field and links to that guide's contents. To open or save a PDF @@ -83,11 +162,8 @@ To receive and share information by email, course team members can: * Join the `openedx-studio`_ Google group to ask questions and participate in discussions with peers at other edX partner organizations and edX staffers. -Wikis and Web Sites -------------------- - -The edX product team maintains the `Open edX Product`_ wiki, which includes the -`Open edX Public Product Roadmap`_. +Course Author Support +---------------------- The `edX Author Support`_ site hosts discussions that are monitored by edX staffers. @@ -145,17 +221,22 @@ Documentation for developers is available on the docs.edx.org web page. contributing to Open edX, options for extending the Open edX platform, using the edX public sandboxes, instrumenting analytics, and testing. -* `Installing, Configuring, and Running the edX Platform`_ provides procedures - for getting an edX developer stack (Devstack) and production stack - (Fullstack) oprerational. - * XBlock_: Open edX courseware components provides preliminary documentation on the XBlock component architecture for building courses. * `edX Open Learning XML Guide`_ provides guidelines for building edX courses - with Open Learning XML (OLX). Note that this guide is currently an Alpha + with Open Learning XML (OLX). Note that this guide is currently an alpha version. +* `edX Data Analytics API`_ provides tools for building applications to view + and analyze student activity in your course. + +* `edX Enrollment API`_ provides tools for building applications to view user + and course enrollment information, and to enroll users in courses. + +* `edX Platform API`_ provides tools for building applications to view course + information and videos. + GitHub ------- @@ -181,29 +262,49 @@ staffers. * For conversations about the code in Open edX, join `edx-code`_. * For conversations about running Open edX, join `openedx-ops`_. -* For conversations about globalization and translation, join `openedx-translation`_. +* For conversations about globalization and translation, + join `openedx-translation`_. Additional Google groups are occasionally formed for individual projects. -.. note:: Please do not report security issues in public. If you have a concern, please email security@edx.org. +.. note:: + Please do not report security issues in public. If you have a concern, + please email security@edx.org. EdX engineers often monitor the Freenode #edx-code IRC channel. -Wikis and Web Sites +Pull Requests ------------------- -The code.edx.org web site_ is an entry point for new contributors. - -The edX Engineering team maintains the `Open Source Home`_ wiki, which provides -insights into the plans, projects, and questions that the edX Open Source team -is working on with the community. - The pull request dashboard_ is a visualization of the count and age of the pull requests (PRs) assigned to teams at edX. Click the bars in this chart to get more information about the PRs. .. _Resources for Students: +.. _Resources for Open edX: + +************************** +Resources for Open edX +************************** + +Hosting providers, platform exenders, core contributors, and course staff all +use Open edX. Starting with the Birch release of Open edX, the following +release-specific documentation is available on docs.edx.org. + +* `Open edX Release Notes`_ provides information on changes in Open edX + releases. + +* `Installing, Configuring, and Running the edX Platform`_ provides procedures + for getting Devstack and Fullstack installed and operational. + +* `Building and Running an Open edX Course`_ is a comprehensive guide with + concepts and procedures to help you build a course in Studio, and then + use the Learning Management System (LMS) to run a course. + + When you are working in Studio, you can access relevant sections of this + guide by clicking **Help** on any page. + ************************** Resources for Students ************************** @@ -211,11 +312,10 @@ Resources for Students Documentation ------------- -The `edX Guide for Students`_ is available on the docs.edx.org web page. As -students are not currently guided to this resource through the coursware, we -encourage course staff to provide links to students as needed in course updates -or discussions. Note that this guide is currently an Alpha version. - +The `edX Guide for Students`_ is available on the docs.edx.org web page. +Because students are not currently guided to this resource through the +courseware, we encourage course staff to provide links to students as needed +in course updates or discussions. In a Course ------------ @@ -225,13 +325,13 @@ interact with other students and with the course team: click **Discussion**. Many courses also offer a wiki for additional resources and materials: click **Wiki**. -Other resources may also be available, such as a course-specific facebook page -or twitter feed or opportunites for Google hangouts. Be sure to check the -**Course Info** page for your course as well as the **Discussion** and **Wiki** -pages. +Other resources might also be available, such as a course-specific Facebook +page or Twitter feed, or opportunities for Google Hangouts. Be sure to check +the **Course Info** page for your course as well as the **Discussion** and +**Wiki** pages. -From time to time, the course team may send email messages to all students. -While you can opt out of these messages, doing so means that you may miss +From time to time, the course team might send email messages to all students. +While you can opt out of these messages, doing so means that you can miss important or time-sensitive information. To change your preferences for course email, click **edX** or **edX edge** at the top of any page. On your dashboard of current courses, locate the course and then click **Email Settings**. @@ -285,3 +385,13 @@ edX Global Community meetup_ group. .. _openedx-ops: http://groups.google.com/forum/#!forum/openedx-ops .. _openedx-translation: http://groups.google.com/forum/#!forum/openedx-translation .. _edx-code: http://groups.google.com/forum/#!forum/edx-code +.. _edx101: https://www.edx.org/course/overview-creating-edx-course-edx-edx101#.VIIJbWTF_yM +.. _edX Data Analytics API: http://edx.readthedocs.org/projects/edx-data-analytics-api/en/latest/index.html +.. _edX Enrollment API: http://edx.readthedocs.org/projects/edx-enrollment-api/en/latest/ +.. _edX Platform API: http://edx.readthedocs.org/projects/edx-platform-api/en/latest/ +.. _edX Partner Portal: https://partners.edx.org +.. _partners.edx.org: https://partners.edx.org +.. _Open edX Portal: https://open.edx.org +.. _open.edx.org/user/register: https://open.edx.org/user/register +.. _Open edX Release Notes: http://edx.readthedocs.org/projects/open-edx-release-notes/en/latest/ +.. _Building and Running an Open edX Course: http://edx.readthedocs.org/projects/open-edx-building-and-running-a-course/en/named-release-birch/ \ No newline at end of file diff --git a/lms/djangoapps/course_structure_api/v0/views.py b/lms/djangoapps/course_structure_api/v0/views.py index ef358daa7a..d238f7b250 100644 --- a/lms/djangoapps/course_structure_api/v0/views.py +++ b/lms/djangoapps/course_structure_api/v0/views.py @@ -77,34 +77,52 @@ class CourseList(CourseViewMixin, ListAPIView): """ **Use Case** - CourseList returns paginated list of courses in the edX Platform. The list can be filtered by course_id. + Get a paginated list of courses in the edX Platform. - **Example Request** + The list can be filtered by course_id. + + Each page in the list can contain up to 10 courses. + + **Example Requests** GET /api/course_structure/v0/courses/ + GET /api/course_structure/v0/courses/?course_id={course_id1},{course_id2} **Response Values** - * id: The unique identifier for the course. + * count: The number of courses in the edX platform. - * name: The name of the course. + * next: The URI to the next page of courses. - * category: The type of content. In this case, the value is always "course". + * previous: The URI to the previous page of courses. - * org: The organization specified for the course. + * num_pages: The number of pages listing courses. - * course: The course number. + * results: A list of courses returned. Each collection in the list + contains these fields. - * org: The run for the course. + * id: The unique identifier for the course. - * uri: The URI to use to get details of the course. + * name: The name of the course. - * image_url: The URI for the course's main image. + * category: The type of content. In this case, the value is always + "course". - * start: Course start date + * org: The organization specified for the course. - * end: Course end date + * run: The run of the course. + + * course: The course number. + + * uri: The URI to use to get details of the course. + + * image_url: The URI for the course's main image. + + * start: The course start date. + + * end: The course end date. If course end date is not specified, the + value is null. """ paginate_by = 10 paginate_by_param = 'page_size' @@ -138,27 +156,34 @@ class CourseDetail(CourseViewMixin, RetrieveAPIView): """ **Use Case** - CourseDetail returns details for a course. + Get details for a specific course. - **Example requests**: + **Example Request**: GET /api/course_structure/v0/courses/{course_id}/ **Response Values** - * category: The type of content. - + * id: The unique identifier for the course. + * name: The name of the course. - * uri: The URI to use to get details of the course. + * category: The type of content. + + * org: The organization that is offering the course. + + * run: The run of the course. * course: The course number. - * due: The due date. For courses, the value is always null. + * uri: The URI to use to get details about the course. - * org: The organization specified for the course. + * image_url: The URI for the course's main image. - * id: The unique identifier for the course. + * start: The course start date. + + * end: The course end date. If course end date is not specified, the + value is null. """ serializer_class = serializers.CourseSerializer @@ -171,7 +196,8 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView): """ **Use Case** - Retrieves course structure. + Get the course structure. This endpoint returns all blocks in the + course. **Example requests**: @@ -179,9 +205,27 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView): **Response Values** - * root: ID of the root node of the structure + * root: The ID of the root node of the course structure. - * blocks: Dictionary mapping IDs to block nodes. + * blocks: A dictionary that maps block IDs to a collection of + information about each block. Each block contains the following + fields. + + * id: The ID of the block. + + * type: The type of block. Possible values include sequential, + vertical, html, problem, video, and discussion. The type can also be + the name of a custom type of block used for the course. + + * display_name: The display name configured for the block. + + * graded: Whether or not the sequential or problem is graded. The + value is true or false. + + * format: The assignment type. + + * children: If the block has child blocks, a list of IDs of the child + blocks. """ serializer_class = serializers.CourseStructureSerializer course = None @@ -205,7 +249,7 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView): """ **Use Case** - Retrieves course grading policy. + Get the course grading policy. **Example requests**: @@ -213,14 +257,16 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView): **Response Values** - * assignment_type: The type of the assignment (e.g. Exam, Homework). Note: These values are course-dependent. - Do not make any assumptions based on assignment type. + * assignment_type: The type of the assignment, as configured by course + staff. For example, course staff might make the assignment types Homework, + Quiz, and Exam. - * count: Number of assignments of the type. + * count: The number of assignments of the type. * dropped: Number of assignments of the type that are dropped. - * weight: Effect of the assignment type on grading. + * weight: The weight, or effect, of the assignment type on the learner's + final grade. """ serializer_class = serializers.GradingPolicySerializer diff --git a/openedx/core/djangoapps/user_api/accounts/views.py b/openedx/core/djangoapps/user_api/accounts/views.py index 8d3fc0e9a4..b76a163517 100644 --- a/openedx/core/djangoapps/user_api/accounts/views.py +++ b/openedx/core/djangoapps/user_api/accounts/views.py @@ -20,79 +20,97 @@ class AccountView(APIView): """ **Use Cases** - Get or update the user's account information. Updates are only supported through merge patch. + Get or update a user's account information. Updates are supported only through merge patch. **Example Requests**: GET /api/user/v0/accounts/{username}/[?view=shared] - PATCH /api/user/v0/accounts/{username}/ with content_type "application/merge-patch+json" + PATCH /api/user/v0/accounts/{username}/{"key":"value"} "application/merge-patch+json" **Response Values for GET** - If the user making the request has username "username", or has "is_staff" access, the following - fields will be returned: + If the user makes the request for her own account, or makes a + request for another account and has "is_staff" access, the response + contains: - * username: username associated with the account (not editable) + * username: The username associated with the account. - * name: full name of the user (must be at least two characters) + * name: The full name of the user. - * email: email for the user (the new email address must be confirmed via a confirmation email, so GET will - not reflect the change until the address has been confirmed) + * email: The confirmed email address for the user. The request + will not return an unconfirmed email address. - * date_joined: date this account was created (not editable), in the string format provided by - datetime (for example, "2014-08-26T17:52:11Z") + * date_joined: The date the account was created, in + the string format provided by datetime (for example, + "2014-08-26T17:52:11Z"). - * gender: null (not set), "m", "f", or "o" + * gender: One of the fullowing values: - * year_of_birth: null or integer year + * "m" + * "f" + * "o" + * null - * level_of_education: null (not set), or one of the following choices: + * year_of_birth: The year the user was born, as an integer, or + null. - * "p" signifying "Doctorate" - * "m" signifying "Master's or professional degree" - * "b" signifying "Bachelor's degree" - * "a" signifying "Associate degree" - * "hs" signifying "Secondary/high school" - * "jhs" signifying "Junior secondary/junior high/middle school" - * "el" signifying "Elementary/primary school" - * "none" signifying "None" - * "o" signifying "Other" + * level_of_education: One of the following values: - * language: null or name of preferred language + * "p": PhD or Doctorate + * "m": Master's or professional degree + * "b": Bachelor's degree + * "a": Associate's degree + * "hs": Secondary/high school + * "jhs": Junior secondary/junior high/middle school + * "el": Elementary/primary school + * "none": "None" + * "o": "Other" + * null: The user did not enter a value. - * country: null (not set), or a Country corresponding to one of the ISO 3166-1 countries + * language: The user's preferred language, or null. - * mailing_address: null or textual representation of mailing address + * country: A ISO 3166 country code or null. - * goals: null or textual representation of goals + * mailing_address: The textual representation of the user's + mailing address, or null. - If a user without "is_staff" access has requested account information for a different user, - only a subset of these fields will be returned. The actual fields returned depend on the configuration - setting ACCOUNT_VISIBILITY_CONFIGURATION, and the visibility preference of the user with username - "username". + * goals: The textual representation of the user's goals, or null. - Note that a user can view which account fields they have shared with other users by requesting their - own username and providing the url parameter "view=shared". + If a user who does not have "is_staff" access requests account + information for a different user, only a subset of these fields is + returned. The fields returned depend on the configuration setting + ACCOUNT_VISIBILITY_CONFIGURATION, and the visibility preference of + the user for whom data is requested. - This method will return a 404 if no user exists with username "username". + Note that a user can view which account fields they have shared with + other users by requesting their own username and providing the url + parameter "view=shared". - **Response for PATCH** + If no user exists with the specified username, a 404 error is + returned. - Users can only modify their own account information. If the requesting user does not have username - "username", this method will return with a status of 404. + **Response Values for PATCH** - This method will also return a 404 if no user exists with username "username". + Users can modify only their own account information. If the user + attempts to modify another user's account, a 404 error is returned. - If "application/merge-patch+json" is not the specified content_type, this method returns a 415 status. + If no user exists with the specified username, a 404 error is + returned. - If the update could not be completed due to validation errors, this method returns a 400 with all - field-specific error messages in the "field_errors" field of the returned JSON. + If "application/merge-patch+json" is not the specified content type, + a 415 error is returned. - If the update could not be completed due to failure at the time of update, this method returns a 400 with - specific errors in the returned JSON. + If the update could not be completed due to validation errors, this + method returns a 400 error with all error messages in the + "field_errors" field of the returned JSON. - If the update is successful, a 204 status is returned with no additional content. + If the update could not be completed due to a failure at the time of + the update, a 400 error is returned with specific errors in the + returned JSON collection. + + If the update is successful, a 204 status is returned with no + additional content. """ authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser) permission_classes = (permissions.IsAuthenticated,)