Skip to content

E
edx-platform
Commit b78f25c8 by Mark Hoeber
Options

Platform API Documentation

parent 2b5a854f
Showing with 1013 additions and 346 deletions
docs/en_us/platform_api/source/authentication.rst
.. _edX API Authentication:
#############################
edX API Authentication
EdX API Authentication
#############################
*************
OAuth 2.0
*************
The edX Platform API uses OAuth 2.0 for authentication. OAuth 2.0 is an open
The edX Platform APIs use OAuth 2.0 for authentication. OAuth 2.0 is an open
standard used by many systems that require secure user authentication. See the
`OAuth 2.0 Standard`_ standard for more information.
***************************************
Registering with Your Open edX Instance
***************************************
To use the edX Platform API with courses on you instance of Open edX, you must register your application with the Open edX server. See the OAuth 2.0 specification for details.
To use the edX Platform API with courses on your instance of Open edX, you must
register your application with the Open edX server. See the OAuth 2.0
specification for details.
.. include:: links.rst
\ No newline at end of file
docs/en_us/platform_api/source/change_log.rst
......@@ -3,7 +3,7 @@ Change Log
############
*****************
January, 2015
2015
*****************
.. list-table::
......@@ -12,5 +12,9 @@ January, 2015
* - Date
- Change
* - 2 April 2015
- Added the :ref:`EdX Platform Course Structure API Version 0`, :ref:`edX
Platform Enrollment API Version 1.0` and :ref:`edX Platform User API
Version 0` sections.
* - 29 January 2015
- Added the :ref:`Get or Change User Status in a Course` section.
docs/en_us/platform_api/source/conf.py
......@@ -40,10 +40,141 @@ MOCK_MODULES = [
'opaque_keys.edx.locator',
'LibraryLocator',
'Location',
'ipware',
'ip',
'ipware.ip',
'get_ip',
'pygeoip',
'ipaddr',
'django_countries',
'fields',
'django_countries.fields',
'opaque_keys',
'opaque_keys.edx',
'opaque_keys.edx.keys',
'CourseKey',
'UsageKey',
'BlockTypeKey',
'opaque_keys.edx.locations',
'SlashSeparatedCourseKey',
'Locator',
'south',
'modelsinspector',
'south.modelsinspector',
'add_introspection_rules',
'courseware',
'access',
'courseware.access',
'is_mobile_available_for_user',
'courseware.model_data',
'courseware.module_render',
'courseware.views',
'util.request',
'eventtracking',
'xmodule',
'xmodule.exceptions',
'xmodule.modulestore',
'xmodule.modulestore.exceptions',
'xmodule.modulestore.django',
'courseware.models',
'milestones',
'milestones.api',
'milestones.models',
'milestones.exceptions',
'ratelimitbackend',
'analytics',
'courseware.courses',
'staticfiles',
'storage',
'staticfiles.storage',
'content',
'xmodule.contentstore',
'xmodule.contentstore.content',
'xblock.exceptions',
'xmodule.seq_module',
'xmodule.vertical_module',
'xmodule.x_module',
'nltk',
'ratelimitbackend',
'ratelimitbackend.exceptions',
'social',
'social.apps',
'social.apps.django_app',
'social.backends',
'mako',
'exceptions',
'mako.exceptions',
'boto',
'exception',
'boto.exception',
'PIL',
'reportlab',
'lib',
'reportlab.lib',
'pdfgen',
'canvas',
'pdfgen',
'pdfgen.canvas',
'reportlab.pdfgen',
'reportlab.pdfgen.canvas',
'reportlab.lib.pagesizes',
'reportlab.lib.units',
'reportlab.lib.styles',
'reportlab.platypus',
'reportlab.platypus.tables',
'boto',
's3',
'connection',
'boto.s3',
'boto.s3.connection',
'boto.s3.key',
'Crypto',
'Crypto.Cipher',
'Crypto.PublicKey',
'openid',
'store',
'interface',
'openid.store',
'store.interface',
'openid.store.interface',
'external_auth.views',
'html_to_text',
'mail_utils',
'ratelimitbackend.backends',
'social.apps.django_app.default',
'social.exceptions',
'social.pipeline',
'xmodule.error_module',
'accounts.api',
'modulestore.mongo.base',
'xmodule.modulestore.mongo',
'xmodule.modulestore.mongo.base',
'edxval',
'edxval.api',
'model_utils',
'model_utils.models',
'model_utils.managers',
'certificates',
'certificates.models',
'certificates.models.GeneratedCertificate',
'shoppingcart',
'shopppingcart.models',
'shopppingcart.api',
'api',
'student',
'student.views',
'student.forms',
'student.models',
'celery',
'celery.task',
'student.roles',
'embargo.models',
'xmodule.vertical_block',
'vertical_block'
]
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = mock.Mock()
sys.modules[mod_name] = mock.Mock(class_that_is_extended=object)
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
......@@ -73,11 +204,9 @@ if not on_rtd: # only import and set the theme if we're building docs locally
root = path('../../../..').abspath()
sys.path.insert(0, root)
sys.path.append(root / "common/lib/xmodule")
sys.path.append(root / "common/djangoapps")
sys.path.append(root / "lms/djangoapps")
sys.path.append(root / "lms/djangoapps/mobile_api")
sys.path.append(root / "lms/djangoapps/mobile_api/course_info")
sys.path.append(root / "lms/djangoapps/mobile_api/users")
sys.path.append(root / "lms/djangoapps/mobile_api/video_outlines")
sys.path.append(root / "openedx/core/djangoapps")
sys.path.insert(
0,
......@@ -105,7 +234,7 @@ extensions = [
'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath',
'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon']
project = u'edX Platform API Version 0.5 Alpha'
project = u'EdX Platform APIs'
copyright = u'2015, edX'
exclude_patterns = ['build', 'links.rst']
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::
:maxdepth: 2
:titlesonly:
read_me
preface
change_log
.. toctree::
:maxdepth: 2
overview
authentication
endpoints
users
course_info
video_outlines
****************
Supported APIs
****************
.. 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 contains docstrings and example responses for:
This page describes how to use the Mobile Course Information API
to complete these actions:
* `Get Course Updates`_
* `Get Course Handouts`_
......@@ -17,28 +16,7 @@ This page contains docstrings and example responses for:
Get Course Updates
*******************
.. .. autoclass:: course_info.views.CourseUpdatesList
**Use Case**
Get the content for course updates.
**Example request**:
``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates``
**Response Values**
A array of course updates. Each course update contains:
* date: The date of the course update.
* content: The content, as a string, of the course update. HTML tags are not
included in the string.
* status: Whether the update is visible or not.
* id: The unique identifier of the update.
.. autoclass:: mobile_api.course_info.views.CourseUpdatesList
**Example response**
......@@ -71,7 +49,7 @@ A array of course updates. Each course update contains:
Get Course Handouts
*******************
.. .. autoclass:: course_info.views.CourseHandoutsList
.. autoclass:: mobile_api.course_info.views.CourseHandoutsList
**Use Case**
......@@ -107,20 +85,7 @@ Get the HTML for course handouts.
Get the Course About Page
**************************
.. .. autoclass:: course_info.views.CourseAboutDetail
.. :members:
**Use Case**
Get the HTML for the course about page.
**Example request**:
``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about``
**Response Values**
* overview: The HTML for the course About page.
.. autoclass:: mobile_api.course_info.views.CourseAboutDetail
**Example response**
......
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.
.. list-table::
:widths: 10 70
: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:
This page describes how to use the Mobile User API to complete
these actions:
* `Get User Details`_
* `Get a User's Course Enrollments`_
......@@ -16,35 +15,7 @@ This page describes how to use the mobile user API to:
Get User Details
*******************
.. .. autoclass:: mobile_api.users.views.UserDetail
.. :members:
**Use Case**
Get information about the specified user and access other resources the user
has permissions for.
Users are redirected to this endpoint after logging in.
You can use the **course_enrollments** value in the response to get a list of
courses the user is enrolled in.
**Example request**
``GET /api/mobile/v0.5/users/{username}``
**Response Values**
* id: The ID of the user.
* username: The username of the currently logged in user.
* email: The email address of the currently logged in user.
* name: The full name of the currently logged in user.
* course_enrollments: The URI to list the courses the currently logged in user
is enrolled in.
.. autoclass:: mobile_api.users.views.UserDetail
**Example response**
......@@ -69,52 +40,7 @@ courses the user is enrolled in.
Get a User's Course Enrollments
**************************************
.. .. autoclass:: users.views.UserCourseEnrollmentsList
.. :members:
**Use Case**
Get information about the courses the currently logged in user is enrolled in.
**Example request**:
``GET /api/mobile/v0.5/users/{username}/course_enrollments/``
**Response Values**
* created: The date the course was created.
* mode: The type of certificate registration for this course: honor or
certified.
* is_active: Whether the course is currently active; true or false.
* course: A collection of data about the course:
* course_about: The URI to get the data for the course About page.
* course_updates: The URI to get data for course updates.
* number: The course number.
* org: The organization that created the course.
* video_outline: The URI to get the list of all vides the user can access in
the course.
* id: The unique ID of the course.
* latest_updates: Reserved for future use.
* end: The end date of the course.
* name: The name of the course.
* course_handouts: The URI to get data for course handouts.
* start: The data and time the course starts.
* course_image: The path to the course image.
.. autoclass:: mobile_api.users.views.UserCourseEnrollmentsList
**Example response**
......@@ -174,36 +100,7 @@ Get information about the courses the currently logged in user is enrolled in.
Get or Change User Status in a Course
**************************************
.. .. autoclass:: mobile_api.users.views.UserCourseStatus
.. :members:
**Use Case**
Get or update the ID of the module that the specified user last visited in the
specified course.
**Example request**
``GET /api/mobile/v0.5/users/{username}/course_status_info/{course_id}``
.. code-block:: http
PATCH /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
body:
last_visited_module_id={module_id}
modification_date={date}
The modification_date is optional. If it is present, the update will
only take effect if the modification_date is later than the
modification_date saved on the server.
**Response Values**
* last_visited_module_id: The ID of the last module visited by the user in the
course.
* last_visited_module_path: The ID of the modules in the path from the last
visited module to the course module.
.. autoclass:: mobile_api.users.views.UserCourseStatus
**Example Response**
......
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 contains docstrings and example responses for:
This page describes how to use the Mobile Video Outlines API to
complete these actions:
* `Get the Video List`_
* `Get a Video Transcript`_
......@@ -15,57 +14,8 @@ This page contains docstrings and example responses for:
Get the Video List
*******************
.. .. autoclass:: video_outlines.views.VideoSummaryList
.. :members:
**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:
.. autoclass:: mobile_api.video_outlines.views.VideoSummaryList
* category: The type of component, in this case always "video".
* video_thumbnail_url: The URL to the thumbnail image for the video, if
available.
* language: The language code for the video.
* name: The display name of the video.
* video_url: The URL to the video file. Use this value to access the video.
* duration: The length of the video, if available.
* transcripts: An array of language codes and URLs to available video
transcripts. Use the URL value to access a transcript for the video.
* id: The unique identifier for the video.
* size: The size of the video file
**Example response**
......@@ -120,16 +70,7 @@ An array of videos in the course. For each video:
Get a Video Transcript
***********************
.. .. autoclass:: video_outlines.views.VideoTranscripts
.. :members:
**Use Case**
Use to get a transcript for a specified video and language.
**Example request**:
``/api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}``
.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts
**Response Values**
......
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
course information and videos for courses on your instance of Open edX.
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 APIs are a rapidly growing and evolving set of capabilities
that enable you to build web, desktop, and mobile applications that work with
your Open edX instance.
The edX Platform API is currently at version 0.5 and is an Alpha release. We
plan on making significant enhancements and changes to the API.
The edX Platform APIs use REST design principles and support the JSON data-
interchange format.
.. caution::
As this is a new and rapidly evolving API, at this time edX does not guarantee
forward compatibility. We encourage you to use and experiment with the API,
while keeping in mind that endpoints may change.
**********************************************
Supported edX Platform API Modules
**********************************************
******************************
edX Platform API Capabilities
******************************
The following edX Platform APIs are currently supported:
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
Course Updates>`, and :ref:`handouts<Get Course Handouts>` for courses the
user is enrolled in.
The following edX Platform APIs are currently experimental:
* 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
* :ref:`EdX Platform Course Structure API Version 0`
* :ref:`edX Platform User API Version 0`
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):
"""
**Use Case**
CourseList returns paginated list of courses in the edX Platform. The list can be filtered by course_id.
Get a paginated list of courses in the edX Platform.
**Example Request**
The list can be filtered by course_id.
Each page in the list can contain up to 10 courses.
**Example Requests**
GET /api/course_structure/v0/courses/
GET /api/course_structure/v0/courses/?course_id={course_id1},{course_id2}
**Response Values**
* id: The unique identifier for the course.
* count: The number of courses in the edX platform.
* name: The name of the course.
* next: The URI to the next page of courses.
* category: The type of content. In this case, the value is always "course".
* previous: The URI to the previous page of courses.
* org: The organization specified for the course.
* num_pages: The number of pages listing courses.
* course: The course number.
* results: A list of courses returned. Each collection in the list
contains these fields.
* org: The run for the course.
* id: The unique identifier for the course.
* uri: The URI to use to get details of the course.
* name: The name of the course.
* image_url: The URI for the course's main image.
* category: The type of content. In this case, the value is always
"course".
* start: Course start date
* org: The organization specified for the course.
* end: Course end date
* run: The run of the course.
* course: The course number.
* uri: The URI to use to get details of the course.
* image_url: The URI for the course's main image.
* start: The course start date.
* end: The course end date. If course end date is not specified, the
value is null.
"""
paginate_by = 10
paginate_by_param = 'page_size'
......@@ -138,27 +156,34 @@ class CourseDetail(CourseViewMixin, RetrieveAPIView):
"""
**Use Case**
CourseDetail returns details for a course.
Get details for a specific course.
**Example requests**:
**Example Request**:
GET /api/course_structure/v0/courses/{course_id}/
**Response Values**
* id: The unique identifier for the course.
* name: The name of the course.
* category: The type of content.
* name: The name of the course.
* org: The organization that is offering the course.
* uri: The URI to use to get details of the course.
* run: The run of the course.
* course: The course number.
* due: The due date. For courses, the value is always null.
* uri: The URI to use to get details about the course.
* org: The organization specified for the course.
* image_url: The URI for the course's main image.
* id: The unique identifier for the course.
* start: The course start date.
* end: The course end date. If course end date is not specified, the
value is null.
"""
serializer_class = serializers.CourseSerializer
......@@ -171,7 +196,8 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView):
"""
**Use Case**
Retrieves course structure.
Get the course structure. This endpoint returns all blocks in the
course.
**Example requests**:
......@@ -179,9 +205,27 @@ class CourseStructure(CourseViewMixin, RetrieveAPIView):
**Response Values**
* root: ID of the root node of the structure
* root: The ID of the root node of the course structure.
* blocks: 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
course = None
......@@ -205,7 +249,7 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView):
"""
**Use Case**
Retrieves course grading policy.
Get the course grading policy.
**Example requests**:
......@@ -213,14 +257,16 @@ class CourseGradingPolicy(CourseViewMixin, ListAPIView):
**Response Values**
* assignment_type: The type of the assignment (e.g. Exam, Homework). Note: These values are course-dependent.
Do not make any assumptions based on assignment type.
* assignment_type: The type of the assignment, as configured by course
staff. For example, course staff might make the assignment types Homework,
Quiz, and Exam.
* count: Number of assignments of the type.
* count: The number of assignments of the type.
* dropped: Number of assignments of the type that are dropped.
* weight: Effect of the assignment type on grading.
* weight: The weight, or effect, of the assignment type on the learner's
final grade.
"""
serializer_class = serializers.GradingPolicySerializer
......
openedx/core/djangoapps/user_api/accounts/views.py
......@@ -20,79 +20,97 @@ class AccountView(APIView):
"""
**Use Cases**
Get or update the user's account information. Updates are only supported through merge patch.
Get or update a user's account information. Updates are supported only through merge patch.
**Example Requests**:
GET /api/user/v0/accounts/{username}/[?view=shared]
PATCH /api/user/v0/accounts/{username}/ with content_type "application/merge-patch+json"
PATCH /api/user/v0/accounts/{username}/{"key":"value"} "application/merge-patch+json"
**Response Values for GET**
If the user making the request has username "username", or has "is_staff" access, the following
fields will be returned:
If the user makes the request for her own account, or makes a
request for another account and has "is_staff" access, the response
contains:
* username: username associated with the account (not editable)
* username: The username associated with the account.
* name: full name of the user (must be at least two characters)
* name: The full name of the user.
* email: email for the user (the new email address must be confirmed via a confirmation email, so GET will
not reflect the change until the address has been confirmed)
* email: The confirmed email address for the user. The request
will not return an unconfirmed email address.
* date_joined: date this account was created (not editable), in the string format provided by
datetime (for example, "2014-08-26T17:52:11Z")
* date_joined: The date the account was created, in
the string format provided by datetime (for example,
"2014-08-26T17:52:11Z").
* gender: null (not set), "m", "f", or "o"
* gender: One of the fullowing values:
* year_of_birth: null or integer year
* "m"
* "f"
* "o"
* null
* level_of_education: null (not set), or one of the following choices:
* year_of_birth: The year the user was born, as an integer, or
null.
* "p" signifying "Doctorate"
* "m" signifying "Master's or professional degree"
* "b" signifying "Bachelor's degree"
* "a" signifying "Associate degree"
* "hs" signifying "Secondary/high school"
* "jhs" signifying "Junior secondary/junior high/middle school"
* "el" signifying "Elementary/primary school"
* "none" signifying "None"
* "o" signifying "Other"
* level_of_education: One of the following values:
* language: null or name of preferred language
* "p": PhD or Doctorate
* "m": Master's or professional degree
* "b": Bachelor's degree
* "a": Associate's degree
* "hs": Secondary/high school
* "jhs": Junior secondary/junior high/middle school
* "el": Elementary/primary school
* "none": "None"
* "o": "Other"
* null: The user did not enter a value.
* country: null (not set), or a Country corresponding to one of the ISO 3166-1 countries
* language: The user's preferred language, or null.
* mailing_address: null or textual representation of mailing address
* country: A ISO 3166 country code or null.
* goals: null or textual representation of goals
* mailing_address: The textual representation of the user's
mailing address, or null.
If a user without "is_staff" access has requested account information for a different user,
only a subset of these fields will be returned. The actual fields returned depend on the configuration
setting ACCOUNT_VISIBILITY_CONFIGURATION, and the visibility preference of the user with username
"username".
* goals: The textual representation of the user's goals, or null.
Note that a user can view which account fields they have shared with other users by requesting their
own username and providing the url parameter "view=shared".
If a user who does not have "is_staff" access requests account
information for a different user, only a subset of these fields is
returned. The fields returned depend on the configuration setting
ACCOUNT_VISIBILITY_CONFIGURATION, and the visibility preference of
the user for whom data is requested.
This method will return a 404 if no user exists with username "username".
Note that a user can view which account fields they have shared with
other users by requesting their own username and providing the url
parameter "view=shared".
**Response for PATCH**
If no user exists with the specified username, a 404 error is
returned.
Users can only modify their own account information. If the requesting user does not have username
"username", this method will return with a status of 404.
**Response Values for PATCH**
This method will also return a 404 if no user exists with username "username".
Users can modify only their own account information. If the user
attempts to modify another user's account, a 404 error is returned.
If "application/merge-patch+json" is not the specified content_type, this method returns a 415 status.
If no user exists with the specified username, a 404 error is
returned.
If the update could not be completed due to validation errors, this method returns a 400 with all
field-specific error messages in the "field_errors" field of the returned JSON.
If "application/merge-patch+json" is not the specified content type,
a 415 error is returned.
If the update could not be completed due to failure at the time of update, this method returns a 400 with
specific errors in the returned JSON.
If the update could not be completed due to validation errors, this
method returns a 400 error with all error messages in the
"field_errors" field of the returned JSON.
If the update is successful, a 204 status is returned with no additional content.
If the update could not be completed due to a failure at the time of
the update, a 400 error is returned with specific errors in the
returned JSON collection.
If the update is successful, a 204 status is returned with no
additional content.
"""
authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)
permission_classes = (permissions.IsAuthenticated,)
......
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