diff --git a/common/djangoapps/enrollment/views.py b/common/djangoapps/enrollment/views.py index 65bc4e6ab0..289d56d2b1 100644 --- a/common/djangoapps/enrollment/views.py +++ b/common/djangoapps/enrollment/views.py @@ -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, diff --git a/docs/en_us/platform_api/source/conf.py b/docs/en_us/platform_api/source/conf.py index 8ebe9c953d..d929c6a560 100644 --- a/docs/en_us/platform_api/source/conf.py +++ b/docs/en_us/platform_api/source/conf.py @@ -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' ] diff --git a/docs/en_us/platform_api/source/course_structure/endpoints.rst b/docs/en_us/platform_api/source/course_structure/endpoints.rst deleted file mode 100644 index fa96bc08dd..0000000000 --- a/docs/en_us/platform_api/source/course_structure/endpoints.rst +++ /dev/null @@ -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 /api/course_structure/v0/courses/ - * - :ref:`Get details about a course ` - - GET /api/course_structure/v0/courses/{course_id}/ - * - :ref:`Get a course's structure, or blocks ` - - GET /api/course_structure/v0/course_structures/{course_id}/ - * - :ref:`Get a course's grading policy ` - - GET /api/course_structure/v0/grading_policies/{course_id}/ - \ No newline at end of file diff --git a/docs/en_us/platform_api/source/course_structure/index.rst b/docs/en_us/platform_api/source/course_structure/index.rst index 0aa08224af..46b68d230d 100644 --- a/docs/en_us/platform_api/source/course_structure/index.rst +++ b/docs/en_us/platform_api/source/course_structure/index.rst @@ -8,5 +8,4 @@ Course Structure API Version 0 :maxdepth: 2 overview - endpoints course_structure diff --git a/docs/en_us/platform_api/source/course_structure/overview.rst b/docs/en_us/platform_api/source/course_structure/overview.rst index 099f362359..ab8e5b7fdc 100644 --- a/docs/en_us/platform_api/source/course_structure/overview.rst +++ b/docs/en_us/platform_api/source/course_structure/overview.rst @@ -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 ` +.. list-table:: + :widths: 10 70 + :header-rows: 1 -* :ref:`Get details about a course ` - -* :ref:`Get a course's structure, or blocks ` - -* :ref:`Get a course's grading policy ` + * - To: + - Use this endpoint: + * - :ref:`Get a list of courses in the edX platform ` + - GET /api/course_structure/v0/courses/ + * - :ref:`Get details about a course ` + - GET /api/course_structure/v0/courses/{course_id}/ + * - :ref:`Get a course's structure, or blocks ` + - GET /api/course_structure/v0/course_structures/{course_id}/ + * - :ref:`Get a course's grading policy ` + - GET /api/course_structure/v0/grading_policies/{course_id}/ diff --git a/docs/en_us/platform_api/source/enrollment/endpoints.rst b/docs/en_us/platform_api/source/enrollment/endpoints.rst deleted file mode 100644 index 377d1be4db..0000000000 --- a/docs/en_us/platform_api/source/enrollment/endpoints.rst +++ /dev/null @@ -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 ` - - /api/enrollment/v1/enrollment/{user_id},{course_id} - * - :ref:`Get enrollment details for a course` - - /api/enrollment/v1/course/{course_id} - * - :ref:`View a user's enrollments ` - - /api/enrollment/v1/enrollment - * - :ref:`Enroll a user in a course ` - - /api/enrollment/v1/enrollment{“course_details”:{“course_id”:“*course_id*”}} \ No newline at end of file diff --git a/docs/en_us/platform_api/source/enrollment/enrollment.rst b/docs/en_us/platform_api/source/enrollment/enrollment.rst index 717498674a..1cc8afd26a 100644 --- a/docs/en_us/platform_api/source/enrollment/enrollment.rst +++ b/docs/en_us/platform_api/source/enrollment/enrollment.rst @@ -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 ` -* :ref:`Get enrollment details for a course` -* :ref:`View a user's enrollments ` -* :ref:`Enroll a user in a course ` +* :ref:`Get the user's enrollment status in a course `. +* :ref:`Get enrollment details for a course`. +* :ref:`View a user's enrollments `. +* :ref:`Enroll a user in a course `. .. _Get the Users Enrollment Status in a Course: @@ -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 diff --git a/docs/en_us/platform_api/source/enrollment/index.rst b/docs/en_us/platform_api/source/enrollment/index.rst index 2bf03fdb5c..8ee8dba5f6 100644 --- a/docs/en_us/platform_api/source/enrollment/index.rst +++ b/docs/en_us/platform_api/source/enrollment/index.rst @@ -8,5 +8,4 @@ Enrollment API Version 1.0 :maxdepth: 2 overview - endpoints enrollment diff --git a/docs/en_us/platform_api/source/enrollment/overview.rst b/docs/en_us/platform_api/source/enrollment/overview.rst index 742c50aaa1..a3e5edfc3e 100644 --- a/docs/en_us/platform_api/source/enrollment/overview.rst +++ b/docs/en_us/platform_api/source/enrollment/overview.rst @@ -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 ` +.. list-table:: + :widths: 20 10 70 + :header-rows: 1 -* :ref:`Get enrollment details for a course` + * - Task + - Method + - Endpoint + * - :ref:`Get the user's enrollment status in a course + ` + - GET + - /api/enrollment/v1/enrollment/{user_id},{course_id} + * - :ref:`Get enrollment details for a course + ` + - GET + - /api/enrollment/v1/course/{course_id} + * - :ref:`View a user's enrollments + ` + - GET + - /api/enrollment/v1/enrollment + * - :ref:`Enroll a user in a course + ` + - POST + - /api/enrollment/v1/enrollment{“course_details”:{“course_id”:“*course_id*”}} -* :ref:`View a user's enrollments ` - -* :ref:`Enroll a user in a course ` diff --git a/docs/en_us/platform_api/source/mobile/course_info.rst b/docs/en_us/platform_api/source/mobile/course_info.rst index e301be61a3..6256cacfa5 100644 --- a/docs/en_us/platform_api/source/mobile/course_info.rst +++ b/docs/en_us/platform_api/source/mobile/course_info.rst @@ -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`. +* - :ref:`Get a list of 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 diff --git a/docs/en_us/platform_api/source/mobile/endpoints.rst b/docs/en_us/platform_api/source/mobile/endpoints.rst deleted file mode 100644 index 3790949c4f..0000000000 --- a/docs/en_us/platform_api/source/mobile/endpoints.rst +++ /dev/null @@ -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` - - /api/mobile/v0.5/users/{username} - * - :ref:`Get course enrollments for about a user` - - /api/mobile/v0.5/users/{username}/course_enrollments/ - * - :ref:`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` - - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates - * - :ref:`Get handouts for a course` - - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts - * - :ref:`Get videos in a course` - - /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run} - * - :ref:`Get a video transcript` - - /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code} diff --git a/docs/en_us/platform_api/source/mobile/index.rst b/docs/en_us/platform_api/source/mobile/index.rst index ff4f8c8767..ca6b78d0d7 100644 --- a/docs/en_us/platform_api/source/mobile/index.rst +++ b/docs/en_us/platform_api/source/mobile/index.rst @@ -8,7 +8,6 @@ Mobile API Version 0.5 :maxdepth: 2 overview - endpoints users course_info video_outlines diff --git a/docs/en_us/platform_api/source/mobile/overview.rst b/docs/en_us/platform_api/source/mobile/overview.rst index 41bf541e47..cef2163f43 100644 --- a/docs/en_us/platform_api/source/mobile/overview.rst +++ b/docs/en_us/platform_api/source/mobile/overview.rst @@ -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` and :ref:`course enrollments` for a user. +======================== +Mobile User API Resource +======================== -* :ref:`Get or change user status in a course ` +.. list-table:: + :widths: 20 10 70 + :header-rows: 1 -* Get :ref:`updates`, and :ref:`handouts` for courses the user is enrolled in. + * - Task + - Method + - Endpoint + * - :ref:`Get details about a user` + - GET + - /api/mobile/v0.5/users/{username} + * - :ref:`Get course enrollments for a user` + - GET + - /api/mobile/v0.5/users/{username}/course_enrollments/ + * - :ref:`Get a user's 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` + - PATCH + - /api/mobile/v0.5/rs/{username}/course_status_info/{course_id} -* Get :ref:`videos` and :ref:`transcripts` 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 + - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates + * - :ref:`Get handouts for a course` + - 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 + - /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run} + * - :ref:`Get a video transcript` + - GET + - /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code} \ No newline at end of file diff --git a/docs/en_us/platform_api/source/mobile/users.rst b/docs/en_us/platform_api/source/mobile/users.rst index 37e27ddc76..f137b0cbfc 100644 --- a/docs/en_us/platform_api/source/mobile/users.rst +++ b/docs/en_us/platform_api/source/mobile/users.rst @@ -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`. +* - :ref:`Get course enrollments for a user`. +* - :ref:`Get a user's status in a course`. +* - :ref:`Change a user's status in a course`. .. _Get User Details: diff --git a/docs/en_us/platform_api/source/mobile/video_outlines.rst b/docs/en_us/platform_api/source/mobile/video_outlines.rst index 0f77cff0bb..e8fb2a5efc 100644 --- a/docs/en_us/platform_api/source/mobile/video_outlines.rst +++ b/docs/en_us/platform_api/source/mobile/video_outlines.rst @@ -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. \ No newline at end of file +.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts \ No newline at end of file diff --git a/docs/en_us/platform_api/source/profile_images/endpoints.rst b/docs/en_us/platform_api/source/profile_images/endpoints.rst deleted file mode 100644 index 6b36655b41..0000000000 --- a/docs/en_us/platform_api/source/profile_images/endpoints.rst +++ /dev/null @@ -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 ` - - POST /api/profile_images/v1/{username}/upload - * - :ref:`Remove profile images ` - - POST /api/profile_images/v1/{username}/remove diff --git a/docs/en_us/platform_api/source/profile_images/index.rst b/docs/en_us/platform_api/source/profile_images/index.rst index 3de6525eee..952538f35e 100644 --- a/docs/en_us/platform_api/source/profile_images/index.rst +++ b/docs/en_us/platform_api/source/profile_images/index.rst @@ -8,5 +8,4 @@ Profile Images API Version 1.0 :maxdepth: 2 overview - endpoints profile_images diff --git a/docs/en_us/platform_api/source/profile_images/overview.rst b/docs/en_us/platform_api/source/profile_images/overview.rst index 78e183e645..f9a5efcc87 100644 --- a/docs/en_us/platform_api/source/profile_images/overview.rst +++ b/docs/en_us/platform_api/source/profile_images/overview.rst @@ -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 ` -* :ref:`Remove profile images ` +.. list-table:: + :widths: 20 10 70 + :header-rows: 1 + + * - Task + - Method + - Endpoint + * - :ref:`Upload a profile image ` + - POST + - /api/profile_images/v1/{username}/upload + * - :ref:`Remove a profile image ` + - POST + - /api/profile_images/v1/{username}/remove \ No newline at end of file diff --git a/docs/en_us/platform_api/source/profile_images/profile_images.rst b/docs/en_us/platform_api/source/profile_images/profile_images.rst index 8866058c88..eb83da5634 100644 --- a/docs/en_us/platform_api/source/profile_images/profile_images.rst +++ b/docs/en_us/platform_api/source/profile_images/profile_images.rst @@ -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 `. +* - :ref:`Remove profile images `. .. _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 diff --git a/docs/en_us/platform_api/source/user/accounts.rst b/docs/en_us/platform_api/source/user/accounts.rst index 1790ebab18..8fc369b501 100644 --- a/docs/en_us/platform_api/source/user/accounts.rst +++ b/docs/en_us/platform_api/source/user/accounts.rst @@ -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" } diff --git a/docs/en_us/platform_api/source/user/endpoints.rst b/docs/en_us/platform_api/source/user/endpoints.rst deleted file mode 100644 index 254766327f..0000000000 --- a/docs/en_us/platform_api/source/user/endpoints.rst +++ /dev/null @@ -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 /api/user/v1/accounts/{username}/[?view=shared] - * - :ref:`Update your account information ` - - PATCH /api/user/v1/accounts/{username}/{“key”:”value”} - * - :ref:`Get a user's preferences information ` - - GET /api/user/v1/preferences/{username}/ - * - :ref:`Update a user's preferences information ` - - PATCH /api/user/v1/preferences/{username}/ - * - :ref:`Get a specific preference ` - - GET /api/user/v1/preferences/{username}/{preference_key} - * - :ref:`Update a specific preference ` - - PUT /api/user/v1/preferences/{username}/{preference_key} - * - :ref:`Delete a specific preference ` - - DELETE /api/user/v1/preferences/{username}/{preference_key} diff --git a/docs/en_us/platform_api/source/user/index.rst b/docs/en_us/platform_api/source/user/index.rst index 97a1bb529a..575de30441 100644 --- a/docs/en_us/platform_api/source/user/index.rst +++ b/docs/en_us/platform_api/source/user/index.rst @@ -8,6 +8,5 @@ User API Version 1.0 :maxdepth: 2 overview - endpoints accounts preferences diff --git a/docs/en_us/platform_api/source/user/overview.rst b/docs/en_us/platform_api/source/user/overview.rst index dbda4f7dbb..7dc96ca262 100644 --- a/docs/en_us/platform_api/source/user/overview.rst +++ b/docs/en_us/platform_api/source/user/overview.rst @@ -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 ` -* :ref:`Get and update the user's preferences information ` -* :ref:`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 + - /api/user/v1/accounts/{username}/[?view=shared] + * - :ref:`Update your 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 + - /api/user/v1/preferences/{username}/ + * - :ref:`Update a user's preferences information + ` + - PATCH + - /api/user/v1/preferences/{username}/ + * - :ref:`Get a specific preference + ` + - GET + - /api/user/v1/preferences/{username}/{preference_key} + * - :ref:`Update a specific preference + ` + - PUT + - /api/user/v1/preferences/{username}/{preference_key} + * - :ref:`Delete a specific preference + ` + - DELETE + - /api/user/v1/preferences/{username}/{preference_key} diff --git a/lms/djangoapps/mobile_api/course_info/views.py b/lms/djangoapps/mobile_api/course_info/views.py index 8c8fd3e694..0da13c12ef 100644 --- a/lms/djangoapps/mobile_api/course_info/views.py +++ b/lms/djangoapps/mobile_api/course_info/views.py @@ -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. """ diff --git a/lms/djangoapps/mobile_api/users/views.py b/lms/djangoapps/mobile_api/users/views.py index 19dae819c9..4622c9c435 100644 --- a/lms/djangoapps/mobile_api/users/views.py +++ b/lms/djangoapps/mobile_api/users/views.py @@ -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 diff --git a/lms/djangoapps/mobile_api/video_outlines/views.py b/lms/djangoapps/mobile_api/video_outlines/views.py index f0a25a77af..bfd27d0d8b 100644 --- a/lms/djangoapps/mobile_api/video_outlines/views.py +++ b/lms/djangoapps/mobile_api/video_outlines/views.py @@ -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. """ diff --git a/openedx/core/djangoapps/profile_images/views.py b/openedx/core/djangoapps/profile_images/views.py index bc51d570d0..6d868a3a5d 100644 --- a/openedx/core/djangoapps/profile_images/views.py +++ b/openedx/core/djangoapps/profile_images/views.py @@ -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) diff --git a/openedx/core/djangoapps/user_api/accounts/views.py b/openedx/core/djangoapps/user_api/accounts/views.py index 832a890769..f25f4fc220 100644 --- a/openedx/core/djangoapps/user_api/accounts/views.py +++ b/openedx/core/djangoapps/user_api/accounts/views.py @@ -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,) diff --git a/openedx/core/djangoapps/user_api/preferences/views.py b/openedx/core/djangoapps/user_api/preferences/views.py index 7070d20c73..d86ca28e68 100644 --- a/openedx/core/djangoapps/user_api/preferences/views.py +++ b/openedx/core/djangoapps/user_api/preferences/views.py @@ -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)