From 0df14f53d97d0031ed91126af80af6d9b803c807 Mon Sep 17 00:00:00 2001 From: Mark Hoeber Date: Wed, 27 May 2015 13:22:16 -0400 Subject: [PATCH] Profile Images API doc --- docs/en_us/platform_api/source/change_log.rst | 2 + docs/en_us/platform_api/source/conf.py | 5 +- .../course_structure/course_structure.rst | 2 +- .../source/enrollment/enrollment.rst | 2 +- docs/en_us/platform_api/source/index.rst | 1 + .../source/mobile/course_info.rst | 60 ------------------- .../platform_api/source/mobile/endpoints.rst | 2 - .../platform_api/source/mobile/overview.rst | 6 +- docs/en_us/platform_api/source/overview.rst | 2 +- .../source/profile_images/endpoints.rst | 21 +++++++ .../source/profile_images/index.rst | 12 ++++ .../source/profile_images/overview.rst | 24 ++++++++ .../source/profile_images/profile_images.rst | 42 +++++++++++++ .../platform_api/source/user/accounts.rst | 2 +- .../platform_api/source/user/preferences.rst | 2 +- .../core/djangoapps/profile_images/views.py | 52 ++++++++++------ 16 files changed, 148 insertions(+), 89 deletions(-) create mode 100644 docs/en_us/platform_api/source/profile_images/endpoints.rst create mode 100644 docs/en_us/platform_api/source/profile_images/index.rst create mode 100644 docs/en_us/platform_api/source/profile_images/overview.rst create mode 100644 docs/en_us/platform_api/source/profile_images/profile_images.rst diff --git a/docs/en_us/platform_api/source/change_log.rst b/docs/en_us/platform_api/source/change_log.rst index d8284b5b9d..9ad8008790 100644 --- a/docs/en_us/platform_api/source/change_log.rst +++ b/docs/en_us/platform_api/source/change_log.rst @@ -12,6 +12,8 @@ Change Log * - Date - Change + * - 10 June 2015 + - Added the section :ref:`Profile Images API Version 1.0`. * - 11 May 2015 - Updated the :ref:`User API ` to Version 1.0. diff --git a/docs/en_us/platform_api/source/conf.py b/docs/en_us/platform_api/source/conf.py index 5b50cea6f2..8ebe9c953d 100644 --- a/docs/en_us/platform_api/source/conf.py +++ b/docs/en_us/platform_api/source/conf.py @@ -182,7 +182,10 @@ MOCK_MODULES = [ 'get_account_settings', 'update_account_settings', 'serializers', - 'PROFILE_IMAGE_KEY_PREFIX' + 'profile_images.images', + 'xmodule.course_module' + + ] for mod_name in MOCK_MODULES: diff --git a/docs/en_us/platform_api/source/course_structure/course_structure.rst b/docs/en_us/platform_api/source/course_structure/course_structure.rst index 31740249ed..83724eed63 100644 --- a/docs/en_us/platform_api/source/course_structure/course_structure.rst +++ b/docs/en_us/platform_api/source/course_structure/course_structure.rst @@ -3,7 +3,7 @@ Course Structure API ######################################## This page contains information on using the Course Structure API to -complete these actions: +complete the following actions. * :ref:`Get a list of courses in the edX platform ` diff --git a/docs/en_us/platform_api/source/enrollment/enrollment.rst b/docs/en_us/platform_api/source/enrollment/enrollment.rst index 5fdd769ba5..717498674a 100644 --- a/docs/en_us/platform_api/source/enrollment/enrollment.rst +++ b/docs/en_us/platform_api/source/enrollment/enrollment.rst @@ -3,7 +3,7 @@ Enrollment API ################################################## This page contains information on using the Enrollment API to complete -these actions: +the following actions. * :ref:`Get the user's enrollment status in a course ` * :ref:`Get enrollment details for a course` diff --git a/docs/en_us/platform_api/source/index.rst b/docs/en_us/platform_api/source/index.rst index fc368fe354..15f51cc59c 100644 --- a/docs/en_us/platform_api/source/index.rst +++ b/docs/en_us/platform_api/source/index.rst @@ -24,6 +24,7 @@ Supported APIs enrollment/index mobile/index + profile_images/index user/index ****************** 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 b9c2f700fc..e301be61a3 100644 --- a/docs/en_us/platform_api/source/mobile/course_info.rst +++ b/docs/en_us/platform_api/source/mobile/course_info.rst @@ -7,7 +7,6 @@ to complete these actions: * `Get Course Updates`_ * `Get Course Handouts`_ -* `Get the Course About Page`_ .. _Get Course Updates: @@ -78,62 +77,3 @@ Get the HTML for course handouts. \n\n" } - -.. _Get the Course About Page: - -************************** -Get the Course About Page -************************** - -.. autoclass:: mobile_api.course_info.views.CourseAboutDetail - -**Example response** - -.. code-block:: json - - HTTP 200 OK - Content-Type: application/json - Vary: Accept - Allow: GET, HEAD, OPTIONS - - { - "overview": "
\n -

About This Course

\n -

Include your long course description here. The long course description should contain 150-400 words.

-

This is paragraph 2 of the long course description. Add more paragraphs as needed. Make sure to enclose them in paragraph tags.

-
\n\n -
\n -

Requirements

\n -

Add information about the skills and knowledge students need to take this course.

\n
\n\n -
\n -

Course Staff

\n -
\n -
\n - \"Course\n -
\n\n -

Staff Member #1

\n -

Biography of instructor/staff member #1

\n -
\n\n -
\n -
\n - \"Course\n -
\n\n -

Staff Member #2

\n -

Biography of instructor/staff member #2

\n -
\n -
\n\n -
\n -
\n -

Frequently Asked Questions

\n -
\n -

What web browser should I use?

\n -

The Open edX platform works best with current versions of Chrome, Firefox or Safari, or with Internet Explorer version 9 and above.

\n -

See our list of supported browsers for the most up-to-date information.

\n -
\n\n -
\n -

Question #2

\n -

Your answer would be displayed here.

\n -
\n -
\n -
" - } \ No newline at end of file diff --git a/docs/en_us/platform_api/source/mobile/endpoints.rst b/docs/en_us/platform_api/source/mobile/endpoints.rst index 5c878cb4c7..3790949c4f 100644 --- a/docs/en_us/platform_api/source/mobile/endpoints.rst +++ b/docs/en_us/platform_api/source/mobile/endpoints.rst @@ -21,8 +21,6 @@ The following tasks and endpoints are currently supported. - /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 a course About page` - - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about * - :ref:`Get updates for a course` - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates * - :ref:`Get handouts for a course` diff --git a/docs/en_us/platform_api/source/mobile/overview.rst b/docs/en_us/platform_api/source/mobile/overview.rst index c04e266a2e..41bf541e47 100644 --- a/docs/en_us/platform_api/source/mobile/overview.rst +++ b/docs/en_us/platform_api/source/mobile/overview.rst @@ -31,10 +31,8 @@ With the Mobile API, you can complete these tasks. * :ref:`Get or change user status in a course ` -* Get :ref:`course information`, :ref:`updates`, and :ref:`handouts` for courses the - user is enrolled in. +* Get :ref:`updates`, and :ref:`handouts` for courses the user is enrolled in. * Get :ref:`videos` and :ref:`transcripts` for courses the user is enrolled in. - diff --git a/docs/en_us/platform_api/source/overview.rst b/docs/en_us/platform_api/source/overview.rst index b9ca73c990..40dcd6abdc 100644 --- a/docs/en_us/platform_api/source/overview.rst +++ b/docs/en_us/platform_api/source/overview.rst @@ -18,9 +18,9 @@ The following edX Platform APIs are currently supported: * :ref:`edX Platform Enrollment API Version 1.0` * :ref:`edX Platform Mobile API Version 0.5` +* :ref:`Profile Images API Version 1.0` * :ref:`edX Platform User API Version 1.0` - ********************************************** Experimental edX Platform API Modules ********************************************** diff --git a/docs/en_us/platform_api/source/profile_images/endpoints.rst b/docs/en_us/platform_api/source/profile_images/endpoints.rst new file mode 100644 index 0000000000..6b36655b41 --- /dev/null +++ b/docs/en_us/platform_api/source/profile_images/endpoints.rst @@ -0,0 +1,21 @@ +################################################ +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 new file mode 100644 index 0000000000..3de6525eee --- /dev/null +++ b/docs/en_us/platform_api/source/profile_images/index.rst @@ -0,0 +1,12 @@ +.. _Profile Images API Version 1.0: + +################################# +Profile Images API Version 1.0 +################################# + +.. toctree:: + :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 new file mode 100644 index 0000000000..78e183e645 --- /dev/null +++ b/docs/en_us/platform_api/source/profile_images/overview.rst @@ -0,0 +1,24 @@ +################################################ +Profile Images Overview +################################################ + +Use the Profile Images API to upload or remove profile images. + +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 +************************************* + +The Profile Images API is currently at version 1.0. + +********************************************** +Profile Images API Capabilities +********************************************** + +With the Profile Images API, you can complete these tasks. + +* :ref:`Upload profile images ` +* :ref:`Remove profile images ` 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 new file mode 100644 index 0000000000..8866058c88 --- /dev/null +++ b/docs/en_us/platform_api/source/profile_images/profile_images.rst @@ -0,0 +1,42 @@ +.. Profile Images API: + +################################################## +Profile Images API +################################################## + +This page contains information on using the Profile Images API to complete +the following actions. + +* `Upload a Profile Image`_ +* `Remove Profile Images`_ + +.. _Upload a Profile Image: + +************************************************** +Upload a Profile Image +************************************************** + +.. autoclass:: profile_images.views.ProfileImageUploadView + +**Example response** + +.. code-block:: json + + HTTP 204 + No Content + + +.. _Remove Profile Images: + +************************************************** +Remove Profile Images +************************************************** + +.. autoclass:: profile_images.views.ProfileImageRemoveView + +**Example response** + +.. code-block:: json + + HTTP 204 + No Content diff --git a/docs/en_us/platform_api/source/user/accounts.rst b/docs/en_us/platform_api/source/user/accounts.rst index 60d9501e56..1790ebab18 100644 --- a/docs/en_us/platform_api/source/user/accounts.rst +++ b/docs/en_us/platform_api/source/user/accounts.rst @@ -5,7 +5,7 @@ User Accounts API ################################################## This page contains information on using the User Accounts API to -complete these actions: +complete the following actions. * `Get and Update the User's Account Information`_ diff --git a/docs/en_us/platform_api/source/user/preferences.rst b/docs/en_us/platform_api/source/user/preferences.rst index 8034555a66..58725324eb 100644 --- a/docs/en_us/platform_api/source/user/preferences.rst +++ b/docs/en_us/platform_api/source/user/preferences.rst @@ -5,7 +5,7 @@ User Preferences API ################################################## This page contains information on using the User Preferences API to -complete these actions: +complete the following actions. * `Get and Update the User's Preferences Information`_ * `Get, Update, or Delete a Specific Preference`_ diff --git a/openedx/core/djangoapps/profile_images/views.py b/openedx/core/djangoapps/profile_images/views.py index 4b1cd4413f..bc51d570d0 100644 --- a/openedx/core/djangoapps/profile_images/views.py +++ b/openedx/core/djangoapps/profile_images/views.py @@ -39,24 +39,33 @@ class ProfileImageUploadView(APIView): """ **Use Cases** - Uploads an image to be used for the user's profile. + Upload an image to be used for the user's profile. - **Example Requests**: + The requesting user must be signed in. The signed in user can only + upload his or her own profile image. + + **Example Requests** POST /api/profile_images/v1/{username}/upload **Response for POST** - Users can only upload their own profile image. 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 the requesting user tries to upload the image for a different user: - This method will also return a 404 if no user exists with username "username". + * If the requesting user has staff access, the request returns a 403 + error. - If the upload could not be performed then this method returns a 400 with specific errors - in the returned JSON. + * If the requesting user does not have staff access, the request returns + a 404 error. - If the update is successful, a 204 status is returned with no additional content. + If no user matches the "username" parameter, the request returns a 404 + error. + + If the upload could not be performed, the request returns a 400 error is + with details. + + If the upload is successful, the request returns a 204 status with no + additional content. """ parser_classes = (MultiPartParser, FormParser,) @@ -116,23 +125,32 @@ class ProfileImageRemoveView(APIView): """ **Use Cases** - Removes all of the profile images associated with the user's account. + Remove all of the profile images associated with the user's account. - **Example Requests**: + The requesting user must be signed in. + + Users with staff access can remove profile images for other user + accounts. + + Users without staff access can only remove their own profile images. + + **Example Requests** POST /api/profile_images/v1/{username}/remove **Response for POST** - Users are authorized to delete their own profile images, while staff can delete images for - any account. All other users will receive a 404 to avoid leaking the existence of the account. + Requesting users who do not have staff access and try to remove another + user's profile image receive a 404 error. - This method will also return a 404 if no user exists with username "username". + If no user matches the "username" parameter, the request returns a 404 + error. - If the delete could not be performed then this method returns a 400 with specific errors - in the returned JSON. + If the request could not remove the image, the request returns a 400 + error with details. - If the delete is successful, a 204 status is returned 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)