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

User preferences API doc

Browse Source
This commit is contained in:
Mark Hoeber
2015-04-28 14:53:49 -04:00
parent 1eeca4d81f
commit 14ea62b3ec
16 changed files with 340 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -12,6 +12,11 @@ Change Log
* - Date
- Change
* - 11 May 2015
- Updated the :ref:`User API <edX Platform User API Version 1.0>` to
Version 1.0.
* -
- Added the :ref:`User Preferences API`.
* - 23 April 2015
- Updated the example responses in :ref:`Get the Users Enrollment Status
in a Course`, :ref:`Get Enrollment Details for a Course`, and :ref:`View
@@ -19,7 +24,7 @@ Change Log
``enrollment_start`` and ``enrollment_end fields``.
* - 2 April 2015
- Added the :ref:`EdX Platform Course Structure API Version 0`, :ref:`edX
Platform Enrollment API Version 1.0` and :ref:`edX Platform User API
Version 0` sections.
Platform Enrollment API Version 1.0` and edX Platform User API
Version 0 sections.
* - 29 January 2015
- Added the :ref:`Get or Change User Status in a Course` section.

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

@@ -170,7 +170,19 @@ MOCK_MODULES = [
'student.roles',
'embargo.models',
'xmodule.vertical_block',
'vertical_block'
'vertical_block',
'errors',
'UserNotFound',
'UserNotAuthorized',
'AccountUpdateError',
'AccountValidationError',
'transaction',
'parsers',
'MergePatchParser',
'get_account_settings',
'update_account_settings',
'serializers',
'PROFILE_IMAGE_KEY_PREFIX'
]
for mod_name in MOCK_MODULES:

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

@@ -1,5 +1,5 @@
########################################
Course Structure API Module
Course Structure API
########################################
This page contains information on using the Course Structure API to

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

@@ -1,5 +1,5 @@
##################################################
Enrollment API Module
Enrollment API
##################################################
This page contains information on using the Enrollment API to complete

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

@@ -24,6 +24,7 @@ Supported APIs
enrollment/index
mobile/index
user/index
******************
Experimental APIs
@@ -33,5 +34,3 @@ Experimental APIs
:maxdepth: 2
course_structure/index
user/index

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

@@ -1,5 +1,5 @@
##################################################
Mobile Course Information API Module
Mobile Course Information API
##################################################
This page describes how to use the Mobile Course Information API

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

@@ -1,5 +1,5 @@
####################################
Mobile User API Module
Mobile User API
####################################
This page describes how to use the Mobile User API to complete

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

@@ -1,5 +1,5 @@
##################################################
Mobile Video Outlines API Module
Mobile Video Outlines API
##################################################
This page describes how to use the Mobile Video Outlines API to

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

@@ -7,7 +7,8 @@ that enable you to build web, desktop, and mobile applications that work with
your Open edX instance.
The edX Platform APIs use REST design principles and support the JSON data-
interchange format.
interchange format. The APIs also use edX OAuth 2.0 for :ref:`authentication
<edX API Authentication>`.
**********************************************
Supported edX Platform API Modules
@@ -17,6 +18,7 @@ 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:`edX Platform User API Version 1.0`
**********************************************
@@ -26,4 +28,3 @@ Experimental edX Platform API Modules
The following edX Platform APIs are currently experimental:
* :ref:`EdX Platform Course Structure API Version 0`
* :ref:`edX Platform User API Version 0`

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

@@ -1,5 +1,7 @@
.. _User Accounts API:
##################################################
User Accounts API Module
User Accounts API
##################################################
This page contains information on using the User Accounts API to
@@ -13,7 +15,129 @@ complete these actions:
Get and Update the User's Account Information
**********************************************
.. autoclass:: user_api.accounts.views.AccountView
.. .. 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.
**Example response showing the user's account information**

20
docs/en_us/platform_api/source/user/endpoints.rst
View File

@@ -15,8 +15,22 @@ The following tasks and endpoints are currently supported.
- Use this endpoint:
* - :ref:`Get a user's account information <Get and Update the User's
Account Information>`
- GET /api/user/v0/accounts/{username}/[?view=shared]
- GET /api/user/v1/accounts/{username}/[?view=shared]
* - :ref:`Update your account information <Get and Update the User's Account
Information>`
- PATCH /api/user/v0/accounts/{username}/{“key”:”value”} “application
/merge-patch+json”
- PATCH /api/user/v1/accounts/{username}/{“key”:”value”}
* - :ref:`Get a user's preferences information <Get and Update the User's
Preferences Information>`
- GET /api/user/v1/preferences/{username}/
* - :ref:`Update a user's preferences information <Get and Update the User's
Preferences Information>`
- PATCH /api/user/v1/preferences/{username}/
* - :ref:`Get a specific preference <Get Update or Delete a Specific
Preference>`
- GET /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Update a specific preference <Get Update or Delete a Specific
Preference>`
- PUT /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Delete a specific preference <Get Update or Delete a Specific
Preference>`
- DELETE /api/user/v1/preferences/{username}/{preference_key}

5
docs/en_us/platform_api/source/user/index.rst
View File

@@ -1,7 +1,7 @@
.. _edX Platform User API Version 0:
.. _edX Platform User API Version 1.0:
#################################
User API Version 0
User API Version 1.0
#################################
.. toctree::
@@ -10,3 +10,4 @@ User API Version 0
overview
endpoints
accounts
preferences

18
docs/en_us/platform_api/source/user/overview.rst
View File

@@ -2,23 +2,17 @@
User API Overview
################################################
Use the User API to view and update account information.
Use the User API to view and update account and preference information.
You can use the User API for web, desktop, and mobile
applications.
You can use the User API for web, desktop, and mobile applications.
*************************************
EdX Platform User API Version 0
User API Version 1.0
*************************************
The User API is currently at version 0. We plan on making
The User API is currently at version 1.0. We plan on making
significant enhancements to this API.
.. caution::
As this is a new and rapidly evolving API, at this time edX does not guarantee
forward compatibility. We encourage you to use and experiment with the API,
while keeping in mind that endpoints might change.
**********************************************
User API Capabilities
**********************************************
@@ -27,3 +21,7 @@ With the User API, you can complete these tasks.
* :ref:`Get and update the users' account information <Get and Update the
User's Account Information>`
* :ref:`Get and update the user's preferences information <Get and Update the
User's Preferences Information>`
* :ref:`Get, update or delete a specific preference: <Get Update or Delete a
Specific Preference>`

53
docs/en_us/platform_api/source/user/preferences.rst Normal file
View File

@@ -0,0 +1,53 @@
.. _User Preferences API:
##################################################
User Preferences API
##################################################
This page contains information on using the User Preferences API to
complete these actions:
* `Get and Update the User's Preferences Information`_
* `Get, Update, or Delete a Specific Preference`_
.. _Get and Update the User's Preferences Information:
**************************************************
Get and Update the User's Preferences Information
**************************************************
.. autoclass:: user_api.preferences.views.PreferencesView
**Example response showing the user's preference information**
.. code-block:: json
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS, PATCH
{
"pref-lang": "en",
"account_privacy": "private"
}
.. _Get Update or Delete a Specific Preference:
**************************************************
Get, Update, or Delete a Specific Preference
**************************************************
.. autoclass:: user_api.preferences.views.PreferencesDetailView
**Example response to a request for the user's account_privacy setting**
.. code-block:: json
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS, PATCH
"private"

115
openedx/core/djangoapps/user_api/accounts/views.py
View File

@@ -24,7 +24,8 @@ class AccountView(APIView):
"""
**Use Cases**
Get or update a user's account information. Updates are supported only through merge patch.
Get or update a user's account information. Updates are supported
only through merge patch.
**Example Requests**:
@@ -38,72 +39,74 @@ class AccountView(APIView):
request for another account and has "is_staff" access, the response
contains:
* username: The username associated with the account.
* username: The username associated with the account.
* name: The full name of the user.
* 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).
* 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".
* 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
* gender: One of the following values:
* year_of_birth: The year the user was born, as an integer, or
null.
* "m"
* "f"
* "o"
* 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.
* year_of_birth: The year the user was born, as an integer, or null.
* language: The user's preferred language, or null.
* level_of_education: One of the following values:
* country: null (not set), or a Country corresponding to one of
the ISO 3166-1 countries.
* "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.
* country: A ISO 3166 country code or null.
* language: The user's preferred language, or null.
* mailing_address: The textual representation of the user's
mailing address, or null.
* country: null (not set), or a Country corresponding to one of the
ISO 3166-1 countries.
* goals: The textual representation of the user's goals, or null.
* country: A ISO 3166 country code or null.
* bio: null or textural representation of user biographical
information ("about me").
* mailing_address: The textual representation of the user's mailing
address, or null.
* is_active: boolean representation of whether a user is active.
* goals: The textual representation of the user's goals, or null.
* 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.
* 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.
requiring parental consent.
* language_proficiencies: array of language preferences.
Each preference is a JSON object with the following keys:
* 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
@@ -114,8 +117,8 @@ class AccountView(APIView):
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.
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
@@ -126,10 +129,10 @@ class AccountView(APIView):
**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.
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.

67
openedx/core/djangoapps/user_api/preferences/views.py
View File

@@ -39,30 +39,48 @@ class PreferencesView(APIView):
**Response Value for GET**
A JSON dictionary will be returned with key/value pairs (all of type String).
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.
If a user without "is_staff" access has requested preferences for a different user,
this method returns a 404.
The list of preferences depends on your implementation. By default,
preferences include:
If the specified username does not exist, this method returns a 404.
* 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``.
If a user without "is_staff" access requests preferences for a
different user, a 404 error is returned.
If the specified username does not exist, a 404 is returned.
**Response for PATCH**
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 staff access but a 404 for ordinary
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.
This method will also return a 404 if no user exists with username "username".
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 "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 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 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 the update is successful, a 204 status is returned with no
additional content.
"""
authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)
@@ -136,30 +154,35 @@ class PreferencesDetailView(APIView):
The preference value will be returned as a JSON string.
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 has requested preferences for a
different user, this method returns a 404.
If the specified username or preference does not exist, this method returns a 404.
If the specified username or preference does not exist, this method
returns a 404.
**Response Values for PUT**
A successful put returns a 204 and no content.
Users can only update their own preferences. 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 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, this method returns a 404.
If the specified preference does not exist, this method returns a
404.
**Response 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 username
"username", this method will return with a status of 403 for staff access but a 404 for ordinary
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, this method returns a
404.
"""
authentication_classes = (OAuth2AuthenticationAllowInactiveUser, SessionAuthenticationAllowInactiveUser)