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

Merge pull request #8214 from edx/markhoeber-doc1987

Browse Source 
Profile Images API doc
This commit is contained in:
Mark Hoeber
2015-06-09 12:51:58 -04:00
parent 65b4e33629 0df14f53d9
commit 7c2a4bc737
16 changed files with 148 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en_us/platform_api/source/change_log.rst
View File

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

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

@@ -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:

2
docs/en_us/platform_api/source/course_structure/course_structure.rst
View File

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

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

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

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

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

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

@@ -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>"
}

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

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

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

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

2
docs/en_us/platform_api/source/overview.rst
View File

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

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

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

12
docs/en_us/platform_api/source/profile_images/index.rst Normal file
View File

@@ -0,0 +1,12 @@
.. _Profile Images API Version 1.0:
#################################
Profile Images API Version 1.0
#################################
.. toctree::
:maxdepth: 2
overview
endpoints
profile_images

24
docs/en_us/platform_api/source/profile_images/overview.rst Normal file
View File

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

42
docs/en_us/platform_api/source/profile_images/profile_images.rst Normal file
View File

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

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

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

2
docs/en_us/platform_api/source/user/preferences.rst
View File

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

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

@@ -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)