Merge pull request #7862 from edx/markhoeber-doc1820

Adds preferences API and updates users to V1

docs/en_us/platform_api/source/change_log.rst

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

docs/en_us/platform_api/source/conf.py

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

docs/en_us/platform_api/source/course_structure/course_structure.rst

 ########################################
-Course Structure API Module
+Course Structure API
 ########################################
 
 This page contains information on using the Course Structure API to

docs/en_us/platform_api/source/enrollment/enrollment.rst

 ##################################################
-Enrollment API Module
+Enrollment API
 ##################################################
 
 This page contains information on using the Enrollment API to complete

docs/en_us/platform_api/source/index.rst

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

docs/en_us/platform_api/source/mobile/course_info.rst

 ##################################################
-Mobile Course Information API Module
+Mobile Course Information API
 ##################################################
 
 This page describes how to use the Mobile Course Information API

docs/en_us/platform_api/source/mobile/users.rst

 ####################################
-Mobile User API Module
+Mobile User API
 ####################################
 
 This page describes how to use the Mobile User API to complete

docs/en_us/platform_api/source/mobile/video_outlines.rst

 ##################################################
-Mobile Video Outlines API Module
+Mobile Video Outlines API
 ##################################################
 
 This page describes how to use the Mobile Video Outlines API to

docs/en_us/platform_api/source/overview.rst

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

docs/en_us/platform_api/source/user/accounts.rst

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

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

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

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

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

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

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

docs/en_us/platform_api/source/user/preferences.rst

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

openedx/core/djangoapps/user_api/accounts/views.py

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

openedx/core/djangoapps/user_api/preferences/views.py

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