Skip to content

E
edx-platform
Commit 7c2a4bc7 by Mark Hoeber
Options

Merge pull request #8214 from edx/markhoeber-doc1987 

Profile Images API doc
parents 65b4e336 0df14f53
Showing with 148 additions and 90 deletions
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 0 → 100644
################################################
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 0 → 100644
.. _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 0 → 100644
################################################
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 0 → 100644
.. 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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment