Andal.LND/edx-platform
6
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Reorganize and update API documentation

Browse Source
This commit is contained in:
Sylvia Pearce
2015-06-24 17:17:16 -04:00
parent 3cdad4677f
commit d2b6ac84d3
29 changed files with 744 additions and 773 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
common/djangoapps/enrollment/views.py
View File

@@ -74,52 +74,65 @@ class EnrollmentUserThrottle(UserRateThrottle, ApiKeyPermissionMixIn):
@can_disable_rate_limit
class EnrollmentView(APIView, ApiKeyPermissionMixIn):
"""
**Use Cases**
**Use Case**
Get the user's enrollment status for a course.
**Example Requests**:
**Example Request**
GET /api/enrollment/v1/enrollment/{username},{course_id}
**Response Values**
* created: The date the user account was created.
If the request for information about the user is successful, an HTTP 200 "OK" response
is returned.
* mode: The enrollment mode of the user in this course.
The HTTP 200 response has the following values.
* is_active: Whether the enrollment is currently active.
* course_details: A collection that includes:
* course_details: A collection that includes the following
values.
* course_end: The date and time when the course closes. If
null, the course never ends.
* course_id: The unique identifier for the course.
* course_modes: An array of data about the enrollment modes
supported for the course. If the request uses the parameter
include_expired=1, the array also includes expired
enrollment modes.
* enrollment_start: The date and time that users can begin enrolling in the course.
If null, enrollment opens immediately when the course is created.
Each enrollment mode collection includes the following
values.
* enrollment_end: The date and time after which users cannot enroll for the course.
If null, the enrollment period never ends.
* currency: The currency of the listed prices.
* description: A description of this mode.
* expiration_datetime: The date and time after which
users cannot enroll in the course in this mode.
* min_price: The minimum price for which a user can
enroll in this mode.
* name: The full name of the enrollment mode.
* slug: The short name for the enrollment mode.
* suggested_prices: A list of suggested prices for
this enrollment mode.
* course_start: The date and time at which the course opens.
If null, the course opens immediately when created.
* course_end: The date and time at which the course closes. If null, the course never ends.
* course_modes: An array of data about the enrollment modes supported for the course.
Each enrollment mode collection includes:
* slug: The short name for the enrollment mode.
* name: The full name of the enrollment mode.
* min_price: The minimum price for which a user can enroll in this mode.
* suggested_prices: A list of suggested prices for this enrollment mode.
* currency: The currency of the listed prices.
* expiration_datetime: The date and time after which users cannot enroll in the course in this mode.
* description: A description of this mode.
* invite_only: Whether students must be invited to enroll in the course; true or false.
* course_end: The date and time at which the course closes. If
null, the course never ends.
* course_start: The date and time when the course opens. If
null, the course opens immediately when it is created.
* enrollment_end: The date and time after which users cannot
enroll for the course. If null, the enrollment period never
ends.
* enrollment_start: The date and time when users can begin
enrolling in the course. If null, enrollment opens
immediately when the course is created.
* invite_only: A value indicating whether students must be
invited to enroll in the course. Possible values are true or
false.
* created: The date the user account was created.
* is_active: Whether the enrollment is currently active.
* mode: The enrollment mode of the user in this course.
* user: The ID of the user.
"""
"""
authentication_classes = OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser
permission_classes = ApiKeyHeaderPermissionIsAuthenticated,
@@ -171,55 +184,64 @@ class EnrollmentView(APIView, ApiKeyPermissionMixIn):
@can_disable_rate_limit
class EnrollmentCourseDetailView(APIView):
"""
**Use Cases**
**Use Case**
Get enrollment details for a course.
Response values include the course schedule and enrollment modes supported by the course.
Use the parameter include_expired=1 to include expired enrollment modes in the response.
Response values include the course schedule and enrollment modes
supported by the course. Use the parameter include_expired=1 to
include expired enrollment modes in the response.
**Note:** Getting enrollment details for a course does not require authentication.
**Note:** Getting enrollment details for a course does not require
authentication.
**Example Requests**:
**Example Requests**
GET /api/enrollment/v1/course/{course_id}
GET /api/v1/enrollment/course/{course_id}?include_expired=1
GET /api/enrollment/v1/course/{course_id}?include_expired=1
**Response Values**
A collection of course enrollments for the user, or for the newly created enrollment.
Each course enrollment contains:
If the request is successful, an HTTP 200 "OK" response is
returned along with a collection of course enrollments for the
user or for the newly created enrollment.
* course_id: The unique identifier of the course.
Each course enrollment contains the following values.
* enrollment_start: The date and time that users can begin enrolling in the course.
If null, enrollment opens immediately when the course is created.
* course_end: The date and time when the course closes. If
null, the course never ends.
* course_id: The unique identifier for the course.
* course_modes: An array of data about the enrollment modes
supported for the course. If the request uses the parameter
include_expired=1, the array also includes expired
enrollment modes.
* enrollment_end: The date and time after which users cannot enroll for the course.
If null, the enrollment period never ends.
Each enrollment mode collection includes the following
values.
* course_start: The date and time at which the course opens.
If null, the course opens immediately when created.
* course_end: The date and time at which the course closes. If null, the course never ends.
* course_modes: An array containing details about the enrollment modes supported for the course.
If the request uses the parameter include_expired=1, the array also includes expired enrollment modes.
Each enrollment mode collection includes:
* slug: The short name for the enrollment mode.
* name: The full name of the enrollment mode.
* min_price: The minimum price for which a user can enroll in this mode.
* suggested_prices: A list of suggested prices for this enrollment mode.
* currency: The currency of the listed prices.
* expiration_datetime: The date and time after which users cannot enroll in the course
in this mode.
* description: A description of this mode.
* expiration_datetime: The date and time after which
users cannot enroll in the course in this mode.
* min_price: The minimum price for which a user can
enroll in this mode.
* name: The full name of the enrollment mode.
* slug: The short name for the enrollment mode.
* suggested_prices: A list of suggested prices for
this enrollment mode.
* invite_only: Whether students must be invited to enroll in the course; true or false.
* course_start: The date and time when the course opens. If
null, the course opens immediately when it is created.
* enrollment_end: The date and time after which users cannot
enroll for the course. If null, the enrollment period never
ends.
* enrollment_start: The date and time when users can begin
enrolling in the course. If null, enrollment opens
immediately when the course is created.
* invite_only: A value indicating whether students must be
invited to enroll in the course. Possible values are true or
false.
"""
authentication_classes = []
@@ -259,100 +281,167 @@ class EnrollmentListView(APIView, ApiKeyPermissionMixIn):
"""
**Use Cases**
1. Get a list of all course enrollments for the currently logged in user.
* Get a list of all course enrollments for the currently signed in user.
2. Enroll the currently logged in user in a course.
* Enroll the currently signed in user in a course.
Currently a user can use this command only to enroll the user in "honor" mode.
Currently a user can use this command only to enroll the user in
honor mode. If honor mode is not supported for the course, the
request fails and returns the available modes.
If honor mode is not supported for the course, the request fails and returns the available modes.
This command can use a server-to-server call to enroll a user in
other modes, such as "verified", "professional", or "credit". If
the mode is not supported for the course, the request will fail
and return the available modes.
A server-to-server call can be used by this command to enroll a user in other modes, such as "verified",
"professional" or "credit". If the mode is not supported for the course, the request will fail and
return the available modes.
You can include other parameters as enrollment attributes for a
specific course mode. For example, for credit mode, you can
include the following parameters to specify the credit provider
attribute.
You can include other parameters as enrollment attributes for specific course mode as needed. For
example, for credit mode, you can include parameters namespace:'credit', name:'provider_id',
value:'UniversityX' to specify credit provider attribute.
* namespace: credit
* name: provider_id
* value: institution_name
**Example Requests**:
**Example Requests**
GET /api/enrollment/v1/enrollment
POST /api/enrollment/v1/enrollment{"mode": "honor", "course_details":{"course_id": "edX/DemoX/Demo_Course"}}
POST /api/enrollment/v1/enrollment{
POST /api/enrollment/v1/enrollment {
"mode": "credit",
"course_details":{"course_id": "edX/DemoX/Demo_Course"},
"enrollment_attributes":[{"namespace": "credit","name": "provider_id","value": "hogwarts",},]
}
**Post Parameters**
**POST Parameters**
* user: The username of the currently logged in user. Optional.
You cannot use the command to enroll a different user.
A POST request can include the following parameters.
* mode: The Course Mode for the enrollment. Individual users cannot upgrade their enrollment mode from
'honor'. Only server-to-server requests can enroll with other modes. Optional.
* user: The username of the currently logged in user. Optional.
You cannot use the command to enroll a different user.
* is_active: A Boolean indicating whether the enrollment is active. Only server-to-server requests are
allowed to deactivate an enrollment. Optional.
* mode: The course mode for the enrollment. Individual users
cannot upgrade their enrollment mode from 'honor'. Only
server-to-server requests can enroll with other modes.
Optional.
* course details: A collection that contains:
* is_active: A Boolean value indicating whether the enrollment
is active. Only server-to-server requests are allowed to
deactivate an enrollment. Optional.
* course details: A collection that includes the following
information.
* course_id: The unique identifier for the course.
* email_opt_in: Optional. A Boolean value that indicates whether
the user wants to receive email from the organization that runs
this course.
* enrollment_attributes: A list of dictionary that contains:
* namespace: Namespace of the attribute
* name: Name of the attribute
* value: Value of the attribute
* is_active: Optional. A Boolean value that indicates whether the
enrollment is active. Only server-to-server requests can
deactivate an enrollment.
* mode: Optional. The course mode for the enrollment. Individual
users cannot upgrade their enrollment mode from "honor". Only
server-to-server requests can enroll with other modes.
* user: Optional. The user ID of the currently logged in user. You
cannot use the command to enroll a different user.
**GET Response Values**
If an unspecified error occurs when the user tries to obtain a
learner's enrollments, the request returns an HTTP 400 "Bad
Request" response.
If the user does not have permission to view enrollment data for
the requested learner, the request returns an HTTP 404 "Not Found"
response.
**POST Response Values**
If the user does not specify a course ID, the specified course
does not exist, or the is_active status is invalid, the request
returns an HTTP 400 "Bad Request" response.
If a user who is not an admin tries to upgrade a learner's course
mode, the request returns an HTTP 403 "Forbidden" response.
If the specified user does not exist, the request returns an HTTP
406 "Not Acceptable" response.
**GET and POST Response Values**
If the request is successful, an HTTP 200 "OK" response is
returned along with a collection of course enrollments for the
user or for the newly created enrollment.
Each course enrollment contains the following values.
* course_details: A collection that includes the following
values.
* course_end: The date and time when the course closes. If
null, the course never ends.
* course_id: The unique identifier for the course.
* email_opt_in: A Boolean indicating whether the user
wishes to opt into email from the organization running this course. Optional.
* course_modes: An array of data about the enrollment modes
supported for the course. If the request uses the parameter
include_expired=1, the array also includes expired
enrollment modes.
* enrollment_attributes: A list of dictionary that contains:
Each enrollment mode collection includes the following
values.
* namespace: Namespace of the attribute
* name: Name of the attribute
* value: Value of the attribute
* currency: The currency of the listed prices.
**Response Values**
* description: A description of this mode.
A collection of course enrollments for the user, or for the newly created enrollment.
Each course enrollment contains:
* expiration_datetime: The date and time after which users
cannot enroll in the course in this mode.
* created: The date the user account was created.
* min_price: The minimum price for which a user can enroll in
this mode.
* mode: The enrollment mode of the user in this course.
* name: The full name of the enrollment mode.
* is_active: Whether the enrollment is currently active.
* slug: The short name for the enrollment mode.
* course_details: A collection that includes:
* suggested_prices: A list of suggested prices for this
enrollment mode.
* course_id: The unique identifier for the course.
* course_start: The date and time when the course opens. If
null, the course opens immediately when it is created.
* enrollment_start: The date and time that users can begin enrolling in the course.
If null, enrollment opens immediately when the course is created.
* enrollment_end: The date and time after which users cannot
enroll for the course. If null, the enrollment period never
ends.
* enrollment_end: The date and time after which users cannot enroll for the course.
If null, the enrollment period never ends.
* enrollment_start: The date and time when users can begin
enrolling in the course. If null, enrollment opens
immediately when the course is created.
* course_start: The date and time at which the course opens.
If null, the course opens immediately when created.
* invite_only: A value indicating whether students must be
invited to enroll in the course. Possible values are true or
false.
* course_end: The date and time at which the course closes. If null, the course never ends.
* created: The date the user account was created.
* course_modes: An array of data about the enrollment modes supported for the course.
Each enrollment mode collection includes:
* is_active: Whether the enrollment is currently active.
* slug: The short name for the enrollment mode.
* name: The full name of the enrollment mode.
* min_price: The minimum price for which a user can enroll in this mode.
* suggested_prices: A list of suggested prices for this enrollment mode.
* currency: The currency of the listed prices.
* expiration_datetime: The date and time after which users cannot enroll in the course
in this mode.
* description: A description of this mode.
* mode: The enrollment mode of the user in this course.
* invite_only: Whether students must be invited to enroll in the course; true or false.
* user: The username of the user.
* user: The username of the user.
"""
authentication_classes = OAuth2AuthenticationAllowInactiveUser, EnrollmentCrossDomainSessionAuth
permission_classes = ApiKeyHeaderPermissionIsAuthenticated,

8
docs/en_us/platform_api/source/conf.py
View File

@@ -183,7 +183,13 @@ MOCK_MODULES = [
'update_account_settings',
'serializers',
'profile_images.images',
'xmodule.course_module'
'xmodule.course_module',
'user_api.accounts.api',
'user_api.accounts.serializers',
'ecommerce_api_client',
'client',
'ecommerce_api_client.client',
'ecommerce_api_client.exceptions'
]

27
docs/en_us/platform_api/source/course_structure/endpoints.rst
View File

@@ -1,27 +0,0 @@
.. _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}/

1
docs/en_us/platform_api/source/course_structure/index.rst
View File

@@ -8,5 +8,4 @@ Course Structure API Version 0
:maxdepth: 2
overview
endpoints
course_structure

28
docs/en_us/platform_api/source/course_structure/overview.rst
View File

@@ -16,16 +16,24 @@ 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
***********************************************
**********************************************
Course Structure API Resources and Endpoints
**********************************************
With the Course Structure API, you can complete these tasks.
The Course Structure API supports the following resources, tasks, methods, and
endpoints.
* :ref:`Get a list of courses in the edX platform <Get a List of Courses>`
.. list-table::
:widths: 10 70
:header-rows: 1
* :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>`
* - 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}/

26
docs/en_us/platform_api/source/enrollment/endpoints.rst
View File

@@ -1,26 +0,0 @@
.. _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*”}}

121
docs/en_us/platform_api/source/enrollment/enrollment.rst
View File

@@ -1,14 +1,17 @@
##################################################
Enrollment API
Enrollment API
##################################################
This page contains information on using the Enrollment API to complete
the following actions.
You can use the Enrollment API to complete the following 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>`
* :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:
@@ -33,37 +36,34 @@ Get the User's Enrollment Status in a Course
"mode": "honor",
"is_active": true,
"course_details": {
"course_end": "2015-06-30T05:00:00Z",
"course_start": "2015-02-05T05:00:00Z",
"course_modes": [
{
"slug": "honor",
"name": "Honor Code Certificate",
"min_price": 0,
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null,
"sku": null
}
],
"enrollment_start": "2015-01-01T05:00:00Z",
"enrollment_end": "2015-02-13T05:00:00Z",
"invite_only": false,
"course_id": "edX/DemoX/Demo_Course"
},
"user": "staff"
"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
************************************
**************************************************
Get the User's Enrollment Information for a Course
**************************************************
.. autoclass:: enrollment.views.EnrollmentCourseDetailView
**Example response showing a user's course enrollments**
**Example response showing a user's course enrollment information**
.. code-block:: json
@@ -73,8 +73,8 @@ Get Enrollment Details for a Course
Allow: GET, HEAD, OPTIONS
{
"course_end": "2015-06-30T05:00:00Z",
"course_start": "2015-02-05T05:00:00Z",
"course_id": "edX/DemoX/Demo_Course",
"enrollment_end": null,
"course_modes": [
{
"slug": "honor",
@@ -83,14 +83,11 @@ Get Enrollment Details for a Course
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null,
"sku": null
"description": null
}
],
"enrollment_start": "2015-01-01T05:00:00Z",
"enrollment_end": "2015-02-13T05:00:00Z",
"invite_only": false,
"course_id": "edX/DemoX/Demo_Course"
"enrollment_start": null,
"invite_only": false
}
@@ -103,7 +100,7 @@ View and Add to a User's Course Enrollments
.. autoclass:: enrollment.views.EnrollmentListView
**Example response showing a user's course enrollments**
**Example response showing a user who is enrolled in two courses**
.. code-block:: json
@@ -114,12 +111,12 @@ View and Add to a User's Course Enrollments
[
{
"created": "2014-11-19T04:06:55Z",
"created": "2014-09-19T18:08:37Z",
"mode": "honor",
"is_active": true,
"course_details": {
"course_end": "2015-06-30T05:00:00Z",
"course_start": "2015-02-05T05:00:00Z",
"course_id": "edX/DemoX/Demo_Course",
"enrollment_end": null,
"course_modes": [
{
"slug": "honor",
@@ -128,21 +125,41 @@ View and Add to a User's Course Enrollments
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null,
"sku": null
"description": null
}
],
"enrollment_start": "2015-01-01T05:00:00Z",
"enrollment_end": "2015-02-13T05:00:00Z",
"invite_only": false,
"course_id": "edX/DemoX/Demo_Course"
"enrollment_start": null,
"invite_only": false
},
"user": "honor"
},
"user": "staff"
}
{
"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**
**Example response showing that a user has been enrolled in a new course**
.. code-block:: json

1
docs/en_us/platform_api/source/enrollment/index.rst
View File

@@ -8,5 +8,4 @@ Enrollment API Version 1.0
:maxdepth: 2
overview
endpoints
enrollment

39
docs/en_us/platform_api/source/enrollment/overview.rst
View File

@@ -5,30 +5,45 @@ Enrollment API Overview
################################################
Use the Enrollment API to view user and course enrollment
information, and to enroll a user in a course.
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
Enrollment API Version and Status
****************************************
The Enrollment API is currently at version 1.0. We plan on making
The Enrollment API is currently at version 1.0. We plan to make
significant enhancements to this API.
********************************************
Enrollment API Capabilities
Enrollment API Endpoints
********************************************
With the Enrollment API, you can complete these tasks.
The Enrollment API supports the following tasks, methods, and endpoints.
* :ref:`Get the user's enrollment status in a course <Get the Users Enrollment
Status in a Course>`
.. list-table::
:widths: 20 10 70
:header-rows: 1
* :ref:`Get enrollment details for a course<Get Enrollment Details for a
Course>`
* - Task
- Method
- Endpoint
* - :ref:`Get the user's enrollment status in a course
<Get the Users Enrollment Status in a Course>`
- GET
- /api/enrollment/v1/enrollment/{user_id},{course_id}
* - :ref:`Get enrollment details for a course
<Get Enrollment Details for a Course>`
- GET
- /api/enrollment/v1/course/{course_id}
* - :ref:`View a user's enrollments
<View and add to a Users Course Enrollments>`
- GET
- /api/enrollment/v1/enrollment
* - :ref:`Enroll a user in a course
<View and add to a Users Course Enrollments>`
- POST
- /api/enrollment/v1/enrollment{“course_details”:{“course_id”:“*course_id*”}}
* :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>`

22
docs/en_us/platform_api/source/mobile/course_info.rst
View File

@@ -1,14 +1,12 @@
##################################################
Mobile Course Information API
Mobile Course Information API Resource
##################################################
This page describes how to use the Mobile Course Information API
to complete these actions:
With the Mobile Course Information API resource, you can complete the following tasks.
* `Get Course Updates`_
* `Get Course Handouts`_
* - :ref:`Get updates about a course<Get Course Updates>`.
* - :ref:`Get a list of course handouts<Get Course Handouts>`.
.. _Get Course Updates:
*******************
@@ -50,18 +48,6 @@ Get Course Handouts
.. autoclass:: mobile_api.course_info.views.CourseHandoutsList
**Use Case**
Get the HTML for course handouts.
**Example request**:
``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts``
**Response Values**
* handouts_html: The HTML for course handouts.
**Example response**
.. code-block:: json

31
docs/en_us/platform_api/source/mobile/endpoints.rst
View File

@@ -1,31 +0,0 @@
.. _edX PlatformMobile API Endpoints:
################################################
Mobile API Endpoints
################################################
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
* - To:
- Use this endpoint:
* - :ref:`Get details about a user<Get User Details>`
- /api/mobile/v0.5/users/{username}
* - :ref:`Get course enrollments for about a user<Get a User's Course Enrollments>`
- /api/mobile/v0.5/users/{username}/course_enrollments/
* - :ref:`Get or change user status in a course<Get or Change User Status in a Course>`
- /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
* - :ref:`Get updates for a course<Get Course Updates>`
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates
* - :ref:`Get handouts for a course<Get Course Handouts>`
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
* - :ref:`Get videos in a course<Get the Video List>`
- /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
* - :ref:`Get a video transcript<Get a Video Transcript>`
- /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}

1
docs/en_us/platform_api/source/mobile/index.rst
View File

@@ -8,7 +8,6 @@ Mobile API Version 0.5
:maxdepth: 2
overview
endpoints
users
course_info
video_outlines

70
docs/en_us/platform_api/source/mobile/overview.rst
View File

@@ -8,7 +8,7 @@ Use the Mobile 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
Mobile API Version and Status
******************************************
The Mobile API is currently at version 0.5 and is an Alpha
@@ -20,19 +20,67 @@ release. We plan on making significant enhancements and changes to the API.
while keeping in mind that endpoints might change.
*************************************
Mobile API Capabilities
Mobile API Resources and Endpoints
*************************************
With the Mobile API, you can complete these tasks.
The Mobile API supports the following resources, tasks, methods, and endpoints.
* Get :ref:`user details<Get User Details>` and :ref:`course enrollments<Get a
User's Course Enrollments>` for a user.
========================
Mobile User API Resource
========================
* :ref:`Get or change user status in a course <Get or Change User Status in a
Course>`
.. list-table::
:widths: 20 10 70
:header-rows: 1
* Get :ref:`updates<Get Course Updates>`, and :ref:`handouts<Get Course
Handouts>` for courses the user is enrolled in.
* - Task
- Method
- Endpoint
* - :ref:`Get details about a user<Get User Details>`
- GET
- /api/mobile/v0.5/users/{username}
* - :ref:`Get course enrollments for a user<Get a User's Course Enrollments>`
- GET
- /api/mobile/v0.5/users/{username}/course_enrollments/
* - :ref:`Get a user's status in a course<Get or Change User Status in a Course>`
- GET
- /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
* - :ref:`Change a user's status in a course<Get or Change User Status in a Course>`
- PATCH
- /api/mobile/v0.5/rs/{username}/course_status_info/{course_id}
* Get :ref:`videos<Get the Video List>` and :ref:`transcripts<Get a Video
Transcript>` for courses the user is enrolled in.
========================================
Mobile Course Information API Resource
========================================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get updates for a course<Get Course Updates>`
- GET
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates
* - :ref:`Get handouts for a course<Get Course Handouts>`
- GET
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
=====================================
Mobile Video Outlines API Resource
=====================================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get videos in a course<Get the Video List>`
- GET
- /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
* - :ref:`Get a video transcript<Get a Video Transcript>`
- GET
- /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}

10
docs/en_us/platform_api/source/mobile/users.rst
View File

@@ -2,12 +2,12 @@
Mobile User API
####################################
This page describes how to use the Mobile User API to complete
these actions:
With the Mobile User API resource, you can complete the following tasks.
* `Get User Details`_
* `Get a User's Course Enrollments`_
* `Get or Change User Status in a Course`_
* - :ref:`Get details about a user<Get User Details>`.
* - :ref:`Get course enrollments for a user<Get a User's Course Enrollments>`.
* - :ref:`Get a user's status in a course<Get or Change User Status in a Course>`.
* - :ref:`Change a user's status in a course<Get or Change User Status in a Course>`.
.. _Get User Details:

6
docs/en_us/platform_api/source/mobile/video_outlines.rst
View File

@@ -70,8 +70,4 @@ Get the Video List
Get a Video Transcript
***********************
.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts
**Response Values**
An HttpResponse with an SRT file download.
.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts

21
docs/en_us/platform_api/source/profile_images/endpoints.rst
View File

@@ -1,21 +0,0 @@
################################################
Profile Images API Endpoints
################################################
You use the Profile Images API to upload or remove profile images.
If you have staff access, you can remove profile images from any user
account.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Upload a profile image <Upload a Profile Image>`
- POST /api/profile_images/v1/{username}/upload
* - :ref:`Remove profile images <Remove Profile Images>`
- POST /api/profile_images/v1/{username}/remove

1
docs/en_us/platform_api/source/profile_images/index.rst
View File

@@ -8,5 +8,4 @@ Profile Images API Version 1.0
:maxdepth: 2
overview
endpoints
profile_images

21
docs/en_us/platform_api/source/profile_images/overview.rst
View File

@@ -9,16 +9,27 @@ The requesting user can upload or remove his or her own profile image.
Users with staff access can remove profile images from any user account.
*************************************
Profile Images API Version 1.0
Profile Images API Version and Status
*************************************
The Profile Images API is currently at version 1.0.
**********************************************
Profile Images API Capabilities
Profile Images API Endpoints
**********************************************
With the Profile Images API, you can complete these tasks.
The Profile Images API supports the following tasks, methods, and endpoints.
* :ref:`Upload profile images <Upload a Profile Image>`
* :ref:`Remove profile images <Remove Profile Images>`
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Upload a profile image <Upload a Profile Image>`
- POST
- /api/profile_images/v1/{username}/upload
* - :ref:`Remove a profile image <Remove a Profile Image>`
- POST
- /api/profile_images/v1/{username}/remove

15
docs/en_us/platform_api/source/profile_images/profile_images.rst
View File

@@ -4,11 +4,10 @@
Profile Images API
##################################################
This page contains information on using the Profile Images API to complete
the following actions.
You can use the Profile Images API to complete the following tasks.
* `Upload a Profile Image`_
* `Remove Profile Images`_
* - :ref:`Upload a profile image <Upload a Profile Image>`.
* - :ref:`Remove profile images <Remove a Profile Image>`.
.. _Upload a Profile Image:
@@ -18,7 +17,7 @@ Upload a Profile Image
.. autoclass:: profile_images.views.ProfileImageUploadView
**Example response**
**Example Response**
.. code-block:: json
@@ -26,15 +25,15 @@ Upload a Profile Image
No Content
.. _Remove Profile Images:
.. _Remove a Profile Image:
**************************************************
Remove Profile Images
Remove a Profile Image
**************************************************
.. autoclass:: profile_images.views.ProfileImageRemoveView
**Example response**
**Example Response**
.. code-block:: json

128
docs/en_us/platform_api/source/user/accounts.rst
View File

@@ -15,129 +15,7 @@ complete the following actions.
Get and Update the User's Account Information
**********************************************
.. .. autoclass:: user_api.accounts.views.AccountView
**Use Cases**
Get or update a user's account information. Updates are supported only through
merge patch.
**Example Requests**:
GET /api/user/v1/accounts/{username}/[?view=shared]
PATCH /api/user/v1/accounts/{username}/{"key":"value"} "application/merge-patch+json"
**Response Values for GET**
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: The username associated with the account.
* 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).
* date_joined: The date the account was created, in the string format provided
by datetime. For example, "2014-08-26T17:52:11Z".
* gender: One of the following values:
* "m"
* "f"
* "o"
* null
* year_of_birth: The year the user was born, as an integer, or null.
* level_of_education: One of the following values:
* "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.
* language: The user's preferred language, or null.
* country: null (not set), or a Country corresponding to one of the ISO 3166-1
countries.
* country: A ISO 3166 country code or null.
* mailing_address: The textual representation of the user's mailing address, or
null.
* goals: The textual representation of the user's goals, or null.
* bio: null or textural representation of user biographical information ("about
me").
* is_active: boolean representation of whether a user is active.
* profile_image: JSON representation of a user's profile image information. The
keys are: the user's profile image:
* "has_image": boolean indicating whether the user has a profile image.
* "image_url_*": absolute URL to various sizes of a user's profile image, where
'*' matches a representation of the corresponding image size such as 'small',
'medium', 'large', and 'full'. These are configurable via
PROFILE_IMAGE_SIZES_MAP.
* requires_parental_consent: true if the user is a minor requiring parental
consent.
* language_proficiencies: array of language preferences. Each preference is a
JSON object with the following keys:
* "code": string ISO 639-1 language code e.g. "en".
For all text fields, clients rendering the values should take care to HTML
escape them to avoid script injections, as the data is stored
exactly as specified. The intention is that plain text is
supported, not HTML.
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.
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 no user exists with the specified username, a 404 error is returned.
**Response Values for PATCH**
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 403
for staff access but a 404 for ordinary users to avoid leaking the existence of
the account.
If no user exists with the specified username, a 404 error is returned.
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 validation errors, this method
returns a 400 error with all error messages in the "field_errors" field of the
returned JSON.
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.
.. autoclass:: user_api.accounts.views.AccountView
**Example response showing the user's account information**
@@ -153,11 +31,11 @@ content.
"name": "John Doe",
"language": "",
"gender": "m",
"year_of_birth": 2007,
"year_of_birth": 1997,
"level_of_education": "m",
"goals": "Professional Development",
"country": US,
"mailing_address": "406 Highland Ave., Somerville, MA 02144",
"mailing_address": "123 Main Street, Anytown, MA 02144",
"email": "johndoe@company.com",
"date_joined": "2015-03-18T13:42:40Z"
}

36
docs/en_us/platform_api/source/user/endpoints.rst
View File

@@ -1,36 +0,0 @@
################################################
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/v1/accounts/{username}/[?view=shared]
* - :ref:`Update your account information <Get and Update the User's Account
Information>`
- PATCH /api/user/v1/accounts/{username}/{“key”:”value”}
* - :ref:`Get a user's preferences information <Get and Update the User's
Preferences Information>`
- GET /api/user/v1/preferences/{username}/
* - :ref:`Update a user's preferences information <Get and Update the User's
Preferences Information>`
- PATCH /api/user/v1/preferences/{username}/
* - :ref:`Get a specific preference <Get Update or Delete a Specific
Preference>`
- GET /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Update a specific preference <Get Update or Delete a Specific
Preference>`
- PUT /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Delete a specific preference <Get Update or Delete a Specific
Preference>`
- DELETE /api/user/v1/preferences/{username}/{preference_key}

1
docs/en_us/platform_api/source/user/index.rst
View File

@@ -8,6 +8,5 @@ User API Version 1.0
:maxdepth: 2
overview
endpoints
accounts
preferences

64
docs/en_us/platform_api/source/user/overview.rst
View File

@@ -7,21 +7,67 @@ Use the User API to view and update account and preference information.
You can use the User API for web, desktop, and mobile applications.
*************************************
User API Version 1.0
User API Version and Status
*************************************
The User API is currently at version 1.0. We plan on making
significant enhancements to this API.
**********************************************
User API Capabilities
User API Resources and Endpoints
**********************************************
With the User API, you can complete these tasks.
The User API supports the following resources, tasks, methods, and endpoints.
* :ref:`Get and update the users' account information <Get and Update the
User's Account Information>`
* :ref:`Get and update the user's preferences information <Get and Update the
User's Preferences Information>`
* :ref:`Get, update or delete a specific preference: <Get Update or Delete a
Specific Preference>`
=============================
User Accounts API Resource
=============================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get a user's account information <Get and Update the User's
Account Information>`
- GET
- /api/user/v1/accounts/{username}/[?view=shared]
* - :ref:`Update your account information <Get and Update the User's Account
Information>`
- PATCH
- /api/user/v1/accounts/{username}/{“key”:”value”}
=============================
User Preferences API Resource
=============================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get a user's preferences information
<Get and Update the User's Preferences Information>`
- GET
- /api/user/v1/preferences/{username}/
* - :ref:`Update a user's preferences information
<Get and Update the User's Preferences Information>`
- PATCH
- /api/user/v1/preferences/{username}/
* - :ref:`Get a specific preference
<Get Update or Delete a Specific Preference>`
- GET
- /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Update a specific preference
<Get Update or Delete a Specific Preference>`
- PUT
- /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Delete a specific preference
<Get Update or Delete a Specific Preference>`
- DELETE
- /api/user/v1/preferences/{username}/{preference_key}

18
lms/djangoapps/mobile_api/course_info/views.py
View File

@@ -19,21 +19,20 @@ class CourseUpdatesList(generics.ListAPIView):
Get the content for course updates.
**Example request**:
**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.
If the request is successful, the request returns an HTTP 200 "OK"
response along with an array of course updates. Each course update
contains the following values.
* content: The content, as an HTML string, of the course update.
* status: Whether the update is visible or not.
* date: The date of the course update.
* id: The unique identifier of the update.
* status: Whether the update is visible or not.
"""
@mobile_course_access()
@@ -64,12 +63,15 @@ class CourseHandoutsList(generics.ListAPIView):
Get the HTML for course handouts.
**Example request**:
**Example Request**
GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
**Response Values**
If the request is successful, the request returns an HTTP 200 "OK"
response along with the following value.
* handouts_html: The HTML for course handouts.
"""

101
lms/djangoapps/mobile_api/users/views.py
View File

@@ -33,31 +33,30 @@ class UserDetail(generics.RetrieveAPIView):
"""
**Use Case**
Get information about the specified user and
access other resources the user has permissions for.
Get information about the specified user and access other resources
the user has permissions for.
Users are redirected to this endpoint after logging in.
Users are redirected to this endpoint after they sign in.
You can use the **course_enrollments** value in
the response to get a list of courses the user is enrolled in.
You can use the **course_enrollments** value in the response to get a
list of courses the user is enrolled in.
**Example request**:
**Example Request**
GET /api/mobile/v0.5/users/{username}
**Response Values**
* id: The ID of the user.
If the request is successful, the request returns an HTTP 200 "OK" response.
* username: The username of the currently logged in user.
The HTTP 200 response has the following values.
* 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
* course_enrollments: The URI to list the courses the currently signed
in user is enrolled in.
* email: The email address of the currently signed in user.
* id: The ID of the user.
* name: The full name of the currently signed in user.
* username: The username of the currently signed in user.
"""
queryset = (
User.objects.all()
@@ -70,27 +69,36 @@ class UserDetail(generics.RetrieveAPIView):
@mobile_view(is_user=True)
class UserCourseStatus(views.APIView):
"""
**Use Case**
**Use Cases**
Get or update the ID of the module that the specified user last visited in the specified course.
Get or update the ID of the module that the specified user last
visited in the specified course.
**Example request**:
**Example Requests**
GET /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
PATCH /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
body:
last_visited_module_id={module_id}
modification_date={date}
**PATCH Parameters**
The body of the PATCH request can include the following parameters.
* 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.
The modification_date parameter is optional. If it is present, the
update will only take effect if the modification_date in the
request 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.
If the request is successful, the request returns an HTTP 200 "OK" response.
The HTTP 200 response has the following values.
* last_visited_module_id: The ID of the last module that the user
visited in the course.
* last_visited_module_path: The ID of the modules in the path from the
last visited module to the course module.
"""
@@ -199,36 +207,45 @@ class UserCourseEnrollmentsList(generics.ListAPIView):
"""
**Use Case**
Get information about the courses the currently logged in user is
Get information about the courses that the currently signed in user is
enrolled in.
**Example request**:
**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.
* certificate: Information about the user's earned certificate in the course.
* url: URL to the downloadable version of the certificate, if exists.
* course: A collection of data about the course:
If the request for information about the user is successful, the
request returns an HTTP 200 "OK" response.
The HTTP 200 response has the following values.
* certificate: Information about the user's earned certificate in the
course.
* course: A collection of the following data about the course.
* course_handouts: The URI to get data for course handouts.
* course_image: The path to the course image.
* course_updates: The URI to get data for course updates.
* end: The end date of the course.
* id: The unique ID of the course.
* latest_updates: Reserved for future use.
* name: The name of the course.
* 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.
* subscription_id: A unique "clean" (alphanumeric with '_') 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.
* start: The date and time when the course starts.
* subscription_id: A unique "clean" (alphanumeric with '_') ID of
the course.
* video_outline: The URI to get the list of all videos that the user
can access in the course.
* created: The date the course was created.
* is_active: Whether the course is currently active. Possible values
are true or false.
* mode: The type of certificate registration for this course (honor or
certified).
* url: URL to the downloadable version of the certificate, if exists.
"""
queryset = CourseEnrollment.objects.all()
serializer_class = CourseEnrollmentSerializer

66
lms/djangoapps/mobile_api/video_outlines/views.py
View File

@@ -30,51 +30,48 @@ class VideoSummaryList(generics.ListAPIView):
Get a list of all videos in the specified course. You can use the
video_url value to access the video file.
**Example request**:
**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:
If the request is successful, the request returns an HTTP 200 "OK"
response along with an array of videos in the course. The array
includes the following information for each video.
* named_path: An array that consists of the display names of the
courseware objects in the path to the video.
* path: An array that specifies the complete path to the video in
the courseware hierarchy. The array contains the following
values.
* category: The type of division in the course outline.
Possible values are "chapter", "sequential", and "vertical".
* name: The display name for the object.
* id: The The unique identifier for the video.
* section_url: The URL to the first page of the section that
contains the video in the Learning Management System.
* summary: An array of data about the video that includes the
following values.
* path: An array containing category, name, and id values specifying the
complete path the the video in the courseware hierarchy. 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
Management 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.
* category: The type of component. This value will always be "video".
* duration: The length of the video, if available.
* id: The unique identifier for the video.
* language: The language code for the video.
* name: The display name of the video.
* size: The size of the video file.
* transcripts: An array of language codes and URLs to available
video transcripts. Use the URL value to access a transcript
for the video.
* video_thumbnail_url: The URL to the thumbnail image for the
video, if available.
* video_url: The URL to the video file. Use this value to access
the video.
* id: The unique identifier for the video.
* size: The size of the video file
* unit_url: The URL to the unit that contains the video in the Learning
Management System.
"""
@mobile_course_access(depth=None)
@@ -97,15 +94,16 @@ class VideoTranscripts(generics.RetrieveAPIView):
"""
**Use Case**
Use to get a transcript for a specified video and language.
Get a transcript for a specified video and language.
**Example request**:
**Example request**
GET /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}
**Response Values**
An HttpResponse with an SRT file download.
If the request is successful, the request returns an HTTP 200 "OK"
response along with an .srt file that you can download.
"""

71
openedx/core/djangoapps/profile_images/views.py
View File

@@ -29,7 +29,7 @@ LOG_MESSAGE_DELETE = 'Deleted images %(image_names)s for user %(user_id)s'
def _make_upload_dt():
"""
Generate a server-side timestamp for the upload. This is in a separate
Generate a server-side timestamp for the upload. This is in a separate
function so its behavior can be overridden in tests.
"""
return datetime.datetime.utcnow().replace(tzinfo=utc)
@@ -37,35 +37,36 @@ def _make_upload_dt():
class ProfileImageUploadView(APIView):
"""
**Use Cases**
**Use Case**
Upload an image to be used for the user's profile.
* Upload an image for the user's profile.
The requesting user must be signed in. The signed in user can only
upload his or her own profile image.
The requesting user must be signed in. The signed in user can only
upload his or her own profile image.
**Example Requests**
**Example Request**
POST /api/profile_images/v1/{username}/upload
**Response for POST**
**Example Responses**
If the requesting user tries to upload the image for a different user:
When the requesting user tries to upload the image for a different user, the
request returns one of the following responses.
* If the requesting user has staff access, the request returns a 403
error.
* If the requesting user has staff access, the request returns an HTTP 403
"Forbidden" response.
* If the requesting user does not have staff access, the request returns
a 404 error.
an HTTP 404 "Not Found" response.
If no user matches the "username" parameter, the request returns a 404
error.
* If no user matches the "username" parameter, the request returns an HTTP
404 "Not Found" response.
If the upload could not be performed, the request returns a 400 error is
with details.
* If the upload could not be performed, the request returns an HTTP 400 "Bad
Request" response with more information.
If the upload is successful, the request returns a 204 status with no
additional content.
* If the upload is successful, the request returns an HTTP 204 "No Content"
response with no additional content.
"""
parser_classes = (MultiPartParser, FormParser,)
@@ -123,34 +124,38 @@ class ProfileImageUploadView(APIView):
class ProfileImageRemoveView(APIView):
"""
**Use Cases**
**Use Case**
Remove all of the profile images associated with the user's account.
* Remove all of the profile images associated with the user's account.
The requesting user must be signed in.
The requesting user must be signed in.
Users with staff access can remove profile images for other user
accounts.
Users with staff access can remove profile images for other user
accounts.
Users without staff access can only remove their own profile images.
Users without staff access can only remove their own profile images.
**Example Requests**
**Example Request**
POST /api/profile_images/v1/{username}/remove
**Response for POST**
**Example Responses**
Requesting users who do not have staff access and try to remove another
user's profile image receive a 404 error.
When the requesting user tries to remove the profile image for a different user, the
request returns one of the following responses.
If no user matches the "username" parameter, the request returns a 404
error.
* If the user does not have staff access, the request returns an HTTP
404 "Not Found" response.
If the request could not remove the image, the request returns a 400
error with details.
* If no user matches the "username" parameter, the request returns an HTTP
404 "Not Found" response.
* If the image could not be removed, the request returns an HTTP 400 "Bad
Request" response with more information.
* If the request successfully removes the image, the request returns an
HTTP 204 "No Content" response with no additional content.
If the request successfully removes the image, the request returns a 204
status with no additional content.
"""
authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)

136
openedx/core/djangoapps/user_api/accounts/views.py
View File

@@ -27,7 +27,7 @@ class AccountView(APIView):
Get or update a user's account information. Updates are supported
only through merge patch.
**Example Requests**:
**Example Requests**
GET /api/user/v1/accounts/{username}/[?view=shared]
@@ -35,29 +35,36 @@ class AccountView(APIView):
**Response Values for GET**
If no user exists with the specified username, an HTTP 404 "Not
Found" response is 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: The username associated with the account.
* 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).
request for another account and has "is_staff" access, an HTTP 200
"OK" response is returned. The response contains the following
values.
* bio: null or textual representation of user biographical
information ("about me").
* country: An ISO 3166 country code or null.
* date_joined: The date the account was created, in the string
format provided by datetime. For example, "2014-08-26T17:52:11Z".
* email: Email address for the user. New email addresses must be confirmed
via a confirmation email, so GET does not reflect the change until
the address has been confirmed.
* gender: One of the following values:
* "m"
* "f"
* "o"
* null
* "f"
* "m"
* "o"
* year_of_birth: The year the user was born, as an integer, or null.
* goals: The textual representation of the user's goals, or null.
* is_active: Boolean representation of whether a user is active.
* language: The user's preferred language, or null.
* language_proficiencies: Array of language preferences. Each
preference is a JSON object with the following keys:
* "code": string ISO 639-1 language code e.g. "en".
* level_of_education: One of the following values:
@@ -70,86 +77,65 @@ class AccountView(APIView):
* "el": Elementary/primary school
* "none": None
* "o": Other
* null: The user did not enter a value.
* language: The user's preferred language, or null.
* country: null (not set), or a Country corresponding to one of the
ISO 3166-1 countries.
* country: A ISO 3166 country code or null.
* null: The user did not enter a value
* mailing_address: The textual representation of the user's mailing
address, or null.
* name: The full name of the user.
* profile_image: A JSON representation of a user's profile image
information. This representation has the following keys.
* goals: The textual representation of the user's goals, or null.
* bio: null or textural representation of user biographical
information ("about me").
* is_active: boolean representation of whether a user is active.
* profile_image: JSON representation of a user's profile image
information. The keys are: the user's profile image:
* "has_image": boolean indicating whether the user has a profile
* "has_image": Boolean indicating whether the user has a profile
image.
* "image_url_*": absolute URL to various sizes of a user's
* "image_url_*": Absolute URL to various sizes of a user's
profile image, where '*' matches a representation of the
corresponding image size such as 'small', 'medium', 'large',
and 'full'. These are configurable via
PROFILE_IMAGE_SIZES_MAP.
corresponding image size, such as 'small', 'medium', 'large',
and 'full'. These are configurable via PROFILE_IMAGE_SIZES_MAP.
* requires_parental_consent: true if the user is a minor
requiring parental consent.
* requires_parental_consent: True if the user is a minor
requiring parental consent.
* username: The username associated with the account.
* year_of_birth: The year the user was born, as an integer, or null.
* language_proficiencies: array of language preferences. Each
preference is a JSON object with the following keys:
* "code": string ISO 639-1 language code e.g. "en".
For all text fields, clients rendering the values should take care
to HTML escape them to avoid script injections, as the data is
stored exactly as specified. The intention is that plain text is
supported, not HTML.
For all text fields, plain text instead of HTML is supported. The
data is stored exactly as specified. Clients must HTML escape
rendered values to avoid script injections.
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.
returned. The returns fields depend on the
ACCOUNT_VISIBILITY_CONFIGURATION configuration setting and the
visibility preference of the user for whom data is requested.
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 no user exists with the specified username, a 404 error is
returned.
Note that a user can view which account fields they have shared
with other users by requesting their own username and providing
the "view=shared" URL parameter.
**Response Values for PATCH**
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 403 for staff access but a 404 for ordinary
users to avoid leaking the existence of the account.
requesting user does not have the specified username and has staff
access, the request returns an HTTP 403 "Forbidden" response. If
the requesting user does not have staff access, the request
returns an HTTP 404 "Not Found" response to avoid revealing the
existence of the account.
If no user exists with the specified username, a 404 error is
returned.
If no user exists with the specified username, an HTTP 404 "Not
Found" response is returned.
If "application/merge-patch+json" is not the specified content type,
a 415 error is returned.
If "application/merge-patch+json" is not the specified content
type, a 415 "Unsupported Media Type" response is returned.
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 validation errors prevent the update, this method returns a 400
"Bad Request" response that includes a "field_errors" field that
lists all error messages.
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 a failure at the time of the update prevents the update, a 400
"Bad Request" error is returned. The JSON collection contains
specific errors.
If the update is successful, a 204 status is returned with no
additional content.
If the update is successful, an HTTP 204 "No Content" response is
returned with no additional content.
"""
authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)
permission_classes = (permissions.IsAuthenticated,)

124
openedx/core/djangoapps/user_api/preferences/views.py
View File

@@ -1,5 +1,6 @@
"""
NOTE: this API is WIP and has not yet been approved. Do not use this API without talking to Christina or Andy.
NOTE: this API is WIP and has not yet been approved. Do not use this API
without talking to Christina or Andy.
For more information, see:
https://openedx.atlassian.net/wiki/display/TNL/User+API
@@ -28,60 +29,62 @@ class PreferencesView(APIView):
"""
**Use Cases**
Get or update the user's preference information. Updates are only supported through merge patch.
Preference values of null in a patch request are treated as requests to remove the preference.
Get or update the user's preference information. Updates are only
supported through merge patch. Preference values of null in a
patch request are treated as requests to remove the preference.
**Example Requests**:
**Example Requests**
GET /api/user/v1/preferences/{username}/
PATCH /api/user/v1/preferences/{username}/ with content_type "application/merge-patch+json"
**Response Value for GET**
**Response Values for GET**
If no user exists with the specified username, an HTTP 404 "Not
Found" response is returned.
If a user without "is_staff" access requests preferences for a
different user, an HTTP 404 "Not Found" message is 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 a JSON dictionary with a key/value pair (of type String)
for each preference.
request for another account and has "is_staff" access, an HTTP 200
"OK" response is returned. The response contains a JSON dictionary
with a key/value pair (of type String) for each preference.
The list of preferences depends on your implementation. By default,
preferences include:
the list includes the following preferences.
* account_privacy: The user's setting for sharing her personal
profile. Possible values are "all_users" or "private".
* pref-lan: The user's preferred language, as set in account
settings.
* account_privacy: The user's setting for sharing her personal
profile. Possible values are ``all_users`` or ``private``.
**Response Values for PATCH**
If a user without "is_staff" access requests preferences for a
different user, a 404 error is returned.
Users can only modify their own preferences. If the
requesting user does not have the specified username and has staff
access, the request returns an HTTP 403 "Forbidden" response. If
the requesting user does not have staff access, the request
returns an HTTP 404 "Not Found" response to avoid revealing the
existence of the account.
If the specified username does not exist, a 404 is returned.
If no user exists with the specified username, an HTTP 404 "Not
Found" response is returned.
**Response for PATCH**
If "application/merge-patch+json" is not the specified content
type, a 415 "Unsupported Media Type" response is returned.
Users can only modify their own preferences. If the requesting user
does not have username "username", this method will return with a
status of 403 for users with staff access but a 404 for ordinary
users to avoid leaking the existence of the account.
If validation errors prevent the update, this method returns a 400
"Bad Request" response that includes a "field_errors" field that
lists all error messages.
This method will also return a 404 if no user exists with username
"username".
If "application/merge-patch+json" is not the specified content_type,
this method returns a 415 status.
If the update could not be completed due to validation errors, this
method returns a 400 with all preference-specific error messages in
the "field_errors" field of the returned JSON.
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 is successful, a 204 status is returned with no
additional content.
If a failure at the time of the update prevents the update, a 400
"Bad Request" error is returned. The JSON collection contains
specific errors.
If the update is successful, an HTTP 204 "No Content" response is
returned with no additional content.
"""
authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)
permission_classes = (permissions.IsAuthenticated, IsUserInUrlOrStaff)
@@ -142,7 +145,7 @@ class PreferencesDetailView(APIView):
Get, create, update, or delete a specific user preference.
**Example Requests**:
**Example Requests**
GET /api/user/v1/preferences/{username}/{preference_key}
@@ -152,38 +155,45 @@ class PreferencesDetailView(APIView):
**Response Values for GET**
The preference value will be returned as a JSON string.
If the specified username or preference does not exist, an HTTP
404 "Not Found" response is returned.
If a user without "is_staff" access has requested preferences for a
different user, this method returns a 404.
If a user without "is_staff" access requests preferences for a
different user, a 404 error is returned.
If the specified username or preference does not exist, this method
returns a 404.
If the user makes the request for her own account, or makes a
request for another account and has "is_staff" access, an HTTP 200
"OK" response is returned that contains a JSON string.
**Response Values for PUT**
A successful put returns a 204 and no content.
Users can only modify their own preferences. If the
requesting user does not have the specified username and has staff
access, the request returns an HTTP 403 "Forbidden" response. If
the requesting user does not have staff access, the request
returns an HTTP 404 "Not Found" response to avoid revealing the
existence of the account.
Users can only modify their own preferences. If the requesting user
does not have username "username", this method will return with a
status of 403 for users with staff access but a 404 for ordinary
users to avoid leaking the existence of the account.
If the specified preference does not exist, an HTTP 404 "Not
Found" response is returned.
If the specified preference does not exist, this method returns a
404.
If the request is successful, a 204 "No Content" status is returned
with no additional content.
**Response for DELETE**
**Response Values for DELETE**
A successful delete returns a 204 and no content.
Users can only delete their own preferences. If the
requesting user does not have the specified username and has staff
access, the request returns an HTTP 403 "Forbidden" response. If
the requesting user does not have staff access, the request
returns an HTTP 404 "Not Found" response to avoid revealing the
existence of the account.
Users can only delete their own preferences. If the requesting user
does not have username "username", this method will return with a
status of 403 for users with staff access but a 404 for ordinary
users to avoid leaking the existence of the account.
If the specified preference does not exist, this method returns a
404.
If the specified preference does not exist, an HTTP 404 "Not
Found" response is returned.
If the update is successful, an HTTP 204 "No Content" response is
returned with no additional content.
"""
authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)
permission_classes = (permissions.IsAuthenticated, IsUserInUrlOrStaff)