Skip to content

E
edx-platform
Commit b78f25c8 by Mark Hoeber
Options

Platform API Documentation

parent 2b5a854f
Showing with 1008 additions and 341 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>`
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