Skip to content

E
edx-platform
Commit b78f25c8 by Mark Hoeber
Options

Platform API Documentation

parent 2b5a854f
Showing with 1156 additions and 378 deletions
docs/en_us/platform_api/source/authentication.rst
.. _edX API Authentication: .. _edX API Authentication:
############################# #############################
edX API Authentication EdX API Authentication
############################# #############################
************* *************
OAuth 2.0 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 standard used by many systems that require secure user authentication. See the
`OAuth 2.0 Standard`_ standard for more information. `OAuth 2.0 Standard`_ standard for more information.
*************************************** ***************************************
Registering with Your Open edX Instance 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 .. include:: links.rst
\ No newline at end of file
docs/en_us/platform_api/source/change_log.rst
...@@ -3,7 +3,7 @@ Change Log ...@@ -3,7 +3,7 @@ Change Log
############ ############
***************** *****************
January, 2015 2015
***************** *****************
.. list-table:: .. list-table::
...@@ -12,5 +12,9 @@ January, 2015 ...@@ -12,5 +12,9 @@ January, 2015
* - Date * - Date
- Change - 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 * - 29 January 2015
- Added the :ref:`Get or Change User Status in a Course` section. - Added the :ref:`Get or Change User Status in a Course` section.
docs/en_us/platform_api/source/conf.py
...@@ -40,10 +40,141 @@ MOCK_MODULES = [ ...@@ -40,10 +40,141 @@ MOCK_MODULES = [
'opaque_keys.edx.locator', 'opaque_keys.edx.locator',
'LibraryLocator', 'LibraryLocator',
'Location', '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: 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' 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 ...@@ -73,11 +204,9 @@ if not on_rtd: # only import and set the theme if we're building docs locally
root = path('../../../..').abspath() root = path('../../../..').abspath()
sys.path.insert(0, root) sys.path.insert(0, root)
sys.path.append(root / "common/lib/xmodule") 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")
sys.path.append(root / "lms/djangoapps/mobile_api") sys.path.append(root / "openedx/core/djangoapps")
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.insert( sys.path.insert(
0, 0,
...@@ -105,7 +234,7 @@ extensions = [ ...@@ -105,7 +234,7 @@ extensions = [
'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath',
'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon'] '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' copyright = u'2015, edX'
exclude_patterns = ['build', 'links.rst'] exclude_patterns = ['build', 'links.rst']
docs/en_us/platform_api/source/course_structure/course_structure.rst 0 → 100644
########################################
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 <Get a List of Courses>`
* :ref:`Get details about a course <Get Course Details>`
* :ref:`Get a course's structure, or blocks <Get the Course Structure>`
* :ref:`Get a courses grading policy <Get the Course 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
},
. . .
]
docs/en_us/platform_api/source/course_structure/endpoints.rst 0 → 100644
.. _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 a List of Courses>`
- GET /api/course_structure/v0/courses/
* - :ref:`Get details about a course <Get Course Details>`
- GET /api/course_structure/v0/courses/{course_id}/
* - :ref:`Get a course's structure, or blocks <Get the Course Structure>`
- GET /api/course_structure/v0/course_structures/{course_id}/
* - :ref:`Get a course's grading policy <Get the Course Grading Policy>`
- GET /api/course_structure/v0/grading_policies/{course_id}/
\ No newline at end of file
docs/en_us/platform_api/source/course_structure/index.rst 0 → 100644
.. _EdX Platform Course Structure API Version 0:
#############################################
Course Structure API Version 0
#############################################
.. toctree::
:maxdepth: 2
overview
endpoints
course_structure
docs/en_us/platform_api/source/course_structure/overview.rst 0 → 100644
.. _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 <Get a List of Courses>`
* :ref:`Get details about a course <Get Course Details>`
* :ref:`Get a course's structure, or blocks <Get the Course Structure>`
* :ref:`Get a course's grading policy <Get the Course Grading Policy>`
docs/en_us/platform_api/source/enrollment/endpoints.rst 0 → 100644
.. _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 <Get the Users Enrollment Status in a Course>`
- /api/enrollment/v1/enrollment/{user_id},{course_id}
* - :ref:`Get enrollment details for a course<Get Enrollment Details for a Course>`
- /api/enrollment/v1/course/{course_id}
* - :ref:`View a user's enrollments <View and add to a Users Course Enrollments>`
- /api/enrollment/v1/enrollment
* - :ref:`Enroll a user in a course <View and add to a Users Course Enrollments>`
- /api/enrollment/v1/enrollment{“course_details”:{“course_id”:“*course_id*”}}
\ No newline at end of file
docs/en_us/platform_api/source/enrollment/enrollment.rst 0 → 100644
##################################################
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 <Get the Users Enrollment Status in a Course>`
* :ref:`Get enrollment details for a course<Get Enrollment Details for a Course>`
* :ref:`View a user's enrollments <View and add to a Users Course Enrollments>`
* :ref:`Enroll a user in a course <View and add to a Users Course Enrollments>`
.. _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
docs/en_us/platform_api/source/enrollment/index.rst 0 → 100644
.. _edX Platform Enrollment API Version 1.0:
########################################
Enrollment API Version 1.0
########################################
.. toctree::
:maxdepth: 2
overview
endpoints
enrollment
docs/en_us/platform_api/source/enrollment/overview.rst 0 → 100644
.. _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 <Get the Users Enrollment
Status in a Course>`
* :ref:`Get enrollment details for a course<Get Enrollment Details for a
Course>`
* :ref:`View a user's enrollments <View and add to a Users Course Enrollments>`
* :ref:`Enroll a user in a course <View and add to a Users Course Enrollments>`
docs/en_us/platform_api/source/index.rst
################################################ ##################
edX Platform API Version 0.5 EdX Platform APIs
################################################ ##################
.. toctree:: .. toctree::
:maxdepth: 2 :titlesonly:
read_me read_me
preface preface
change_log
.. toctree::
:maxdepth: 2
overview overview
authentication authentication
endpoints
users ****************
course_info Supported APIs
video_outlines ****************
.. toctree::
:maxdepth: 2
enrollment/index
mobile/index
******************
Experimental APIs
******************
.. toctree::
:maxdepth: 2
course_structure/index
user/index
docs/en_us/platform_api/source/course_info.rst → docs/en_us/platform_api/source/mobile/course_info.rst
################################################## ##################################################
Course Information API Module Mobile Course Information API Module
################################################## ##################################################
.. module:: mobile_api This page describes how to use the Mobile Course Information API
to complete these actions:
This page contains docstrings and example responses for:
* `Get Course Updates`_ * `Get Course Updates`_
* `Get Course Handouts`_ * `Get Course Handouts`_
...@@ -17,28 +16,7 @@ This page contains docstrings and example responses for: ...@@ -17,28 +16,7 @@ This page contains docstrings and example responses for:
Get Course Updates Get Course Updates
******************* *******************
.. .. autoclass:: course_info.views.CourseUpdatesList .. autoclass:: mobile_api.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.
**Example response** **Example response**
...@@ -71,7 +49,7 @@ A array of course updates. Each course update contains: ...@@ -71,7 +49,7 @@ A array of course updates. Each course update contains:
Get Course Handouts Get Course Handouts
******************* *******************
.. .. autoclass:: course_info.views.CourseHandoutsList .. autoclass:: mobile_api.course_info.views.CourseHandoutsList
**Use Case** **Use Case**
...@@ -107,20 +85,7 @@ Get the HTML for course handouts. ...@@ -107,20 +85,7 @@ Get the HTML for course handouts.
Get the Course About Page Get the Course About Page
************************** **************************
.. .. autoclass:: course_info.views.CourseAboutDetail .. autoclass:: mobile_api.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.
**Example response** **Example response**
......
docs/en_us/platform_api/source/endpoints.rst → docs/en_us/platform_api/source/mobile/endpoints.rst
.. _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. The following tasks and endpoints are currently supported.
.. list-table:: .. list-table::
:widths: 10 70 :widths: 10 70
:header-rows: 1 :header-rows: 1
......
docs/en_us/platform_api/source/mobile/index.rst 0 → 100644
.. _edX Platform Mobile API Version 0.5:
#####################################
Mobile API Version 0.5
#####################################
.. toctree::
:maxdepth: 2
overview
endpoints
users
course_info
video_outlines
docs/en_us/platform_api/source/mobile/overview.rst 0 → 100644
.. _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<Get User Details>` and :ref:`course enrollments<Get a
User's Course Enrollments>` for a user.
* :ref:`Get or change user status in a course <Get or Change User Status in a
Course>`
* Get :ref:`course information<Get the Course About Page>`, :ref:`updates<Get
Course Updates>`, and :ref:`handouts<Get Course Handouts>` for courses the
user is enrolled in.
* Get :ref:`videos<Get the Video List>` and :ref:`transcripts<Get a Video
Transcript>` for courses the user is enrolled in.
\ No newline at end of file
docs/en_us/platform_api/source/users.rst → docs/en_us/platform_api/source/mobile/users.rst
######################### ####################################
User API Module Mobile User API Module
######################### ####################################
.. module:: mobile_api This page describes how to use the Mobile User API to complete
these actions:
This page describes how to use the mobile user API to:
* `Get User Details`_ * `Get User Details`_
* `Get a User's Course Enrollments`_ * `Get a User's Course Enrollments`_
...@@ -16,35 +15,7 @@ This page describes how to use the mobile user API to: ...@@ -16,35 +15,7 @@ This page describes how to use the mobile user API to:
Get User Details Get User Details
******************* *******************
.. .. autoclass:: mobile_api.users.views.UserDetail .. 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.
**Example response** **Example response**
...@@ -69,52 +40,7 @@ courses the user is enrolled in. ...@@ -69,52 +40,7 @@ courses the user is enrolled in.
Get a User's Course Enrollments Get a User's Course Enrollments
************************************** **************************************
.. .. autoclass:: users.views.UserCourseEnrollmentsList .. autoclass:: mobile_api.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.
**Example response** **Example response**
...@@ -174,36 +100,7 @@ Get information about the courses the currently logged in user is enrolled in. ...@@ -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 Get or Change User Status in a Course
************************************** **************************************
.. .. autoclass:: mobile_api.users.views.UserCourseStatus .. 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.
**Example Response** **Example Response**
......
docs/en_us/platform_api/source/video_outlines.rst → docs/en_us/platform_api/source/mobile/video_outlines.rst
################################################## ##################################################
Video Outlines API Module Mobile Video Outlines API Module
################################################## ##################################################
.. module:: mobile_api This page describes how to use the Mobile Video Outlines API to
complete these actions:
This page contains docstrings and example responses for:
* `Get the Video List`_ * `Get the Video List`_
* `Get a Video Transcript`_ * `Get a Video Transcript`_
...@@ -15,57 +14,8 @@ This page contains docstrings and example responses for: ...@@ -15,57 +14,8 @@ This page contains docstrings and example responses for:
Get the Video List Get the Video List
******************* *******************
.. .. autoclass:: video_outlines.views.VideoSummaryList .. autoclass:: mobile_api.video_outlines.views.VideoSummaryList
.. :members:
**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** **Example response**
...@@ -120,16 +70,7 @@ An array of videos in the course. For each video: ...@@ -120,16 +70,7 @@ An array of videos in the course. For each video:
Get a Video Transcript Get a Video Transcript
*********************** ***********************
.. .. autoclass:: video_outlines.views.VideoTranscripts .. autoclass:: mobile_api.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}``
**Response Values** **Response Values**
......
docs/en_us/platform_api/source/overview.rst
.. _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 The edX Platform APIs are a rapidly growing and evolving set of capabilities
course information and videos for courses on your instance of Open edX. 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.
You can use the edX Platform API for web, desktop, and mobile applications.
*************************************
edX Platform API Version 0.5, Alpha
*************************************
The edX Platform API is currently at version 0.5 and is an Alpha release. We The edX Platform APIs use REST design principles and support the JSON data-
plan on making significant enhancements and changes to the API. interchange format.
.. caution:: **********************************************
As this is a new and rapidly evolving API, at this time edX does not guarantee Supported edX Platform API Modules
forward compatibility. We encourage you to use and experiment with the API, **********************************************
while keeping in mind that endpoints may change.
****************************** The following edX Platform APIs are currently supported:
edX Platform API Capabilities
******************************
With the edX Platform API, you can: * :ref:`edX Platform Enrollment API Version 1.0`
* :ref:`edX Platform Mobile API Version 0.5`
* Get :ref:`user details<Get User Details>` and :ref:`course enrollments<Get a
User's Course Enrollments>` for a user.
* :ref:`Get or change user status in a course <Get or Change User Status in a **********************************************
Course>` Experimental edX Platform API Modules
**********************************************
* Get :ref:`course information<Get the Course About Page>`, :ref:`updates<Get The following edX Platform APIs are currently experimental:
Course Updates>`, and :ref:`handouts<Get Course Handouts>` for courses the
user is enrolled in.
* Get :ref:`videos<Get the Video List>` and :ref:`transcripts<Get a Video * :ref:`EdX Platform Course Structure API Version 0`
Transcript>` for courses the user is enrolled in. * :ref:`edX Platform User API Version 0`
\ No newline at end of file
docs/en_us/platform_api/source/user/accounts.rst 0 → 100644
##################################################
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"
}
docs/en_us/platform_api/source/user/endpoints.rst 0 → 100644
################################################
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 and Update the User's
Account Information>`
- GET /api/user/v0/accounts/{username}/[?view=shared]
* - :ref:`Update your account information <Get and Update the User's Account
Information>`
- PATCH /api/user/v0/accounts/{username}/{“key”:”value”} “application
/merge-patch+json”
docs/en_us/platform_api/source/user/index.rst 0 → 100644
.. _edX Platform User API Version 0:
#################################
User API Version 0
#################################
.. toctree::
:maxdepth: 2
overview
endpoints
accounts
docs/en_us/platform_api/source/user/overview.rst 0 → 100644
################################################
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 <Get and Update the
User's Account Information>`
docs/en_us/shared/preface.rst
.. _Preface: .. _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 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 Course teams, researchers, developers, students: the edX community includes
groups with a range of reasons for using the platform and objectives to 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 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. ...@@ -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: To help you find what you need, browse the edX offerings in these categories:
* :ref:`Resources for Course Teams` * `The edX Partner Portal`_
* :ref:`Resources for Researchers` * `The Open edX Portal`_
* :ref:`Resources for Developers` * `Release Announcements through the Open edX Portal`_
* :ref:`Resources for Students` * `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 All members of the edX community are encouraged to make use of any of the
resources described in this preface. 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 System Status
*********************** ***********************
...@@ -42,6 +111,14 @@ Course teams include faculty, instructional designers, course staff, discussion ...@@ -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 moderators, and others who contribute to the creation and delivery of courses
on edx.org or edX Edge. 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 Documentation
------------- -------------
...@@ -65,7 +142,9 @@ Documentation for course teams is available on the docs.edx.org web page. ...@@ -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 peer- and self- evaluations of responses to a question. Note that this new
feature is in limited release. 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 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 **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: ...@@ -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 * Join the `openedx-studio`_ Google group to ask questions and participate in
discussions with peers at other edX partner organizations and edX staffers. discussions with peers at other edX partner organizations and edX staffers.
Wikis and Web Sites Course Author Support
------------------- ----------------------
The edX product team maintains the `Open edX Product`_ wiki, which includes the
`Open edX Public Product Roadmap`_.
The `edX Author Support`_ site hosts discussions that are monitored by edX The `edX Author Support`_ site hosts discussions that are monitored by edX
staffers. staffers.
...@@ -145,17 +221,22 @@ Documentation for developers is available on the docs.edx.org web page. ...@@ -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 contributing to Open edX, options for extending the Open edX platform, using
the edX public sandboxes, instrumenting analytics, and testing. 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 * XBlock_: Open edX courseware components provides preliminary documentation
on the XBlock component architecture for building courses. on the XBlock component architecture for building courses.
* `edX Open Learning XML Guide`_ provides guidelines for building edX 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. 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 GitHub
------- -------
...@@ -181,29 +262,49 @@ staffers. ...@@ -181,29 +262,49 @@ staffers.
* For conversations about the code in Open edX, join `edx-code`_. * For conversations about the code in Open edX, join `edx-code`_.
* For conversations about running Open edX, join `openedx-ops`_. * 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. 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. 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 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 pull requests (PRs) assigned to teams at edX. Click the bars in this chart to
get more information about the PRs. get more information about the PRs.
.. _Resources for Students: .. _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 Resources for Students
************************** **************************
...@@ -211,11 +312,10 @@ Resources for Students ...@@ -211,11 +312,10 @@ Resources for Students
Documentation Documentation
------------- -------------
The `edX Guide for Students`_ is available on the docs.edx.org web page. As The `edX Guide for Students`_ is available on the docs.edx.org web page.
students are not currently guided to this resource through the coursware, we Because students are not currently guided to this resource through the
encourage course staff to provide links to students as needed in course updates courseware, we encourage course staff to provide links to students as needed
or discussions. Note that this guide is currently an Alpha version. in course updates or discussions.
In a Course In a Course
------------ ------------
...@@ -225,13 +325,13 @@ interact with other students and with the course team: click **Discussion**. ...@@ -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 Many courses also offer a wiki for additional resources and materials: click
**Wiki**. **Wiki**.
Other resources may also be available, such as a course-specific facebook page Other resources might also be available, such as a course-specific Facebook
or twitter feed or opportunites for Google hangouts. Be sure to check the page or Twitter feed, or opportunities for Google Hangouts. Be sure to check
**Course Info** page for your course as well as the **Discussion** and **Wiki** the **Course Info** page for your course as well as the **Discussion** and
pages. **Wiki** pages.
From time to time, the course team may send email messages to all students. 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 may miss 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 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 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**. of current courses, locate the course and then click **Email Settings**.
...@@ -285,3 +385,13 @@ edX Global Community meetup_ group. ...@@ -285,3 +385,13 @@ edX Global Community meetup_ group.
.. _openedx-ops: http://groups.google.com/forum/#!forum/openedx-ops .. _openedx-ops: http://groups.google.com/forum/#!forum/openedx-ops
.. _openedx-translation: http://groups.google.com/forum/#!forum/openedx-translation .. _openedx-translation: http://groups.google.com/forum/#!forum/openedx-translation
.. _edx-code: http://groups.google.com/forum/#!forum/edx-code .. _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
lms/djangoapps/course_structure_api/v0/views.py
...@@ -77,34 +77,52 @@ class CourseList(CourseViewMixin, ListAPIView): ...@@ -77,34 +77,52 @@ class CourseList(CourseViewMixin, ListAPIView):
""" """
**Use Case** **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/
GET /api/course_structure/v0/courses/?course_id={course_id1},{course_id2} GET /api/course_structure/v0/courses/?course_id={course_id1},{course_id2}
**Response Values** **Response Values**
* count: The number of courses in the edX platform.
* next: The URI to the next page of courses.
* previous: The URI to the previous page of courses.
* num_pages: The number of pages listing courses.
* results: A list of courses returned. Each collection in the list
contains these fields.
* id: The unique identifier for the course. * id: The unique identifier for the course.
* name: The name of the course. * name: The name of the course.
* category: The type of content. In this case, the value is always "course". * category: The type of content. In this case, the value is always
"course".
* org: The organization specified for the course. * org: The organization specified for the course.
* course: The course number. * run: The run of the course.
* org: The run for the course. * course: The course number.
* uri: The URI to use to get details of the course. * uri: The URI to use to get details of the course.
* image_url: The URI for the course's main image. * image_url: The URI for the course's main image.
* start: Course start date * start: The course start date.
* end: Course end date * end: The course end date. If course end date is not specified, the
value is null.
""" """
paginate_by = 10 paginate_by = 10
paginate_by_param = 'page_size' paginate_by_param = 'page_size'
...@@ -138,27 +156,34 @@ class CourseDetail(CourseViewMixin, RetrieveAPIView): ...@@ -138,27 +156,34 @@ class CourseDetail(CourseViewMixin, RetrieveAPIView):
""" """
**Use Case** **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}/ GET /api/course_structure/v0/courses/{course_id}/
**Response Values** **Response Values**
* category: The type of content. * id: The unique identifier for the course.
* name: The name of 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. * 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 serializer_class = serializers.CourseSerializer
...@@ -171,7 +196,8 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView): ...@@ -171,7 +196,8 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView):
""" """
**Use Case** **Use Case**
Retrieves course structure. Get the course structure. This endpoint returns all blocks in the
course.
**Example requests**: **Example requests**:
...@@ -179,9 +205,27 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView): ...@@ -179,9 +205,27 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView):
**Response Values** **Response Values**
* root: ID of the root node of the structure * root: The ID of the root node of the course structure.
* 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.
* blocks: Dictionary mapping IDs to block nodes. * children: If the block has child blocks, a list of IDs of the child
blocks.
""" """
serializer_class = serializers.CourseStructureSerializer serializer_class = serializers.CourseStructureSerializer
course = None course = None
...@@ -205,7 +249,7 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView): ...@@ -205,7 +249,7 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView):
""" """
**Use Case** **Use Case**
Retrieves course grading policy. Get the course grading policy.
**Example requests**: **Example requests**:
...@@ -213,14 +257,16 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView): ...@@ -213,14 +257,16 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView):
**Response Values** **Response Values**
* assignment_type: The type of the assignment (e.g. Exam, Homework). Note: These values are course-dependent. * assignment_type: The type of the assignment, as configured by course
Do not make any assumptions based on assignment type. 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. * 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 serializer_class = serializers.GradingPolicySerializer
......
openedx/core/djangoapps/user_api/accounts/views.py
...@@ -20,79 +20,97 @@ class AccountView(APIView): ...@@ -20,79 +20,97 @@ class AccountView(APIView):
""" """
**Use Cases** **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**: **Example Requests**:
GET /api/user/v0/accounts/{username}/[?view=shared] 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** **Response Values for GET**
If the user making the request has username "username", or has "is_staff" access, the following If the user makes the request for her own account, or makes a
fields will be returned: 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 * email: The confirmed email address for the user. The request
not reflect the change until the address has been confirmed) will not return an unconfirmed email address.
* date_joined: date this account was created (not editable), in the string format provided by * date_joined: The date the account was created, in
datetime (for example, "2014-08-26T17:52:11Z") 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" * level_of_education: One of the following values:
* "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"
* 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, * goals: The textual representation of the user's goals, or null.
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".
Note that a user can view which account fields they have shared with other users by requesting their If a user who does not have "is_staff" access requests account
own username and providing the url parameter "view=shared". 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 **Response Values for PATCH**
"username", this method will return with a status of 404.
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 If "application/merge-patch+json" is not the specified content type,
field-specific error messages in the "field_errors" field of the returned JSON. 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 If the update could not be completed due to validation errors, this
specific errors in the returned JSON. 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) authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)
permission_classes = (permissions.IsAuthenticated,) permission_classes = (permissions.IsAuthenticated,)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment