Merge pull request #8214 from edx/markhoeber-doc1987

Profile Images API doc

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 <edX Platform User API Version 1.0>` to
        Version 1.0.

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:

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 <Get a List of Courses>`
 

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 <Get the Users Enrollment Status in a Course>`
 * :ref:`Get enrollment details for a course<Get Enrollment Details for a Course>`

docs/en_us/platform_api/source/index.rst

@@ -24,6 +24,7 @@ Supported APIs
 
     enrollment/index
     mobile/index
+    profile_images/index
     user/index
 
 ******************

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.
                           </ol>\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": "<section class=\"about\">\n
-                     <h2>About This Course</h2>\n   
-                     <p>Include your long course description here. The long course description should contain 150-400 words.</p>
-                     <p>This is paragraph 2 of the long course description. Add more paragraphs as needed. Make sure to enclose them in paragraph tags.</p>
-                     </section>\n\n 
-                     <section class=\"prerequisites\">\n   
-                     <h2>Requirements</h2>\n
-                     <p>Add information about the skills and knowledge students need to take this course.</p>\n </section>\n\n
-                     <section class=\"course-staff\">\n   
-                     <h2>Course Staff</h2>\n   
-                     <article class=\"teacher\">\n     
-                     <div class=\"teacher-image\">\n       
-                     <img src=\"/static/images/placeholder-faculty.png\" align=\"left\" style=\"margin:0 20 px 0\" alt=\"Course Staff Image #1\">\n     
-                     </div>\n\n     
-                     <h3>Staff Member #1</h3>\n     
-                     <p>Biography of instructor/staff member #1</p>\n   
-                     </article>\n\n   
-                     <article class=\"teacher\">\n     
-                     <div class=\"teacher-image\">\n       
-                     <img src=\"/static/images/placeholder-faculty.png\" align=\"left\" style=\"margin:0 20 px 0\" alt=\"Course Staff Image #2\">\n     
-                     </div>\n\n     
-                     <h3>Staff Member #2</h3>\n     
-                     <p>Biography of instructor/staff member #2</p>\n   
-                     </article>\n 
-                     </section>\n\n 
-                     <section class=\"faq\">\n   
-                     <section class=\"responses\">\n     
-                     <h2>Frequently Asked Questions</h2>\n     
-                     <article class=\"response\">\n       
-                     <h3>What web browser should I use?</h3>\n
-                     <p>The Open edX platform works best with current versions of Chrome, Firefox or Safari, or with Internet Explorer version 9 and above.</p>\n
-                     <p>See our <a href=\"http://edx.readthedocs.org/en/latest/browsers.html\">list of supported browsers</a> for the most up-to-date information.</p>\n     
-                     </article>\n\n     
-                     <article class=\"response\">\n       
-                     <h3>Question #2</h3>\n       
-                     <p>Your answer would be displayed here.</p>\n     
-                     </article>\n   
-                     </section>\n 
-                     </section>"
-    }
\ No newline at end of file

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<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<Get the Course About Page>`
-     - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about
    * - :ref:`Get updates for a course<Get Course Updates>`
      - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates   
    * - :ref:`Get handouts for a course<Get Course Handouts>`

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 or Change User Status in a
   Course>`
 
-* Get :ref:`course information<Get the Course About Page>`, :ref:`updates<Get
-  Course Updates>`, and :ref:`handouts<Get Course Handouts>` for courses the
-  user is enrolled in.
+* Get :ref:`updates<Get Course Updates>`, and :ref:`handouts<Get Course
+  Handouts>` for courses the user is enrolled in.
 
 * Get :ref:`videos<Get the Video List>` and :ref:`transcripts<Get a Video
   Transcript>` for courses the user is enrolled in.
-  

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
 **********************************************

docs/en_us/platform_api/source/profile_images/endpoints.rst

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

docs/en_us/platform_api/source/profile_images/index.rst

+.. _Profile Images API Version 1.0:
+
+#################################
+Profile Images API Version 1.0
+#################################
+
+.. toctree::
+    :maxdepth: 2
+    
+    overview
+    endpoints
+    profile_images

docs/en_us/platform_api/source/profile_images/overview.rst

+################################################
+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 <Upload a Profile Image>`
+* :ref:`Remove profile images <Remove Profile Images>`

docs/en_us/platform_api/source/profile_images/profile_images.rst

+.. 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

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`_
 

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`_

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:
+
+        * If the requesting user has staff access, the request returns a 403
+          error.
+
+        * If the requesting user does not have staff access, the request returns
+          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 upload could not be performed then this method returns a 400 with specific errors
-        in the returned JSON.
+        If the upload could not be performed, the request returns a 400 error is
+        with details.
 
-        If the update is successful, a 204 status is returned with no additional content.
+        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.
+
+        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**:
+    **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)