From 14ea62b3ecbc46ddfd5ab880d6fb79ae5f968ba7 Mon Sep 17 00:00:00 2001 From: Mark Hoeber Date: Tue, 28 Apr 2015 14:53:49 -0400 Subject: [PATCH] User preferences API doc --- docs/en_us/platform_api/source/change_log.rst | 9 +- docs/en_us/platform_api/source/conf.py | 14 +- .../course_structure/course_structure.rst | 2 +- .../source/enrollment/enrollment.rst | 2 +- docs/en_us/platform_api/source/index.rst | 3 +- .../source/mobile/course_info.rst | 2 +- .../platform_api/source/mobile/users.rst | 2 +- .../source/mobile/video_outlines.rst | 2 +- docs/en_us/platform_api/source/overview.rst | 5 +- .../platform_api/source/user/accounts.rst | 128 +++++++++++++++++- .../platform_api/source/user/endpoints.rst | 20 ++- docs/en_us/platform_api/source/user/index.rst | 5 +- .../platform_api/source/user/overview.rst | 18 ++- .../platform_api/source/user/preferences.rst | 53 ++++++++ .../djangoapps/user_api/accounts/views.py | 115 ++++++++-------- .../djangoapps/user_api/preferences/views.py | 67 ++++++--- 16 files changed, 340 insertions(+), 107 deletions(-) create mode 100644 docs/en_us/platform_api/source/user/preferences.rst diff --git a/docs/en_us/platform_api/source/change_log.rst b/docs/en_us/platform_api/source/change_log.rst index 6236a10ef2..d8284b5b9d 100644 --- a/docs/en_us/platform_api/source/change_log.rst +++ b/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 ` 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. diff --git a/docs/en_us/platform_api/source/conf.py b/docs/en_us/platform_api/source/conf.py index cffb48a0ad..5b3a0ec90a 100644 --- a/docs/en_us/platform_api/source/conf.py +++ b/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: diff --git a/docs/en_us/platform_api/source/course_structure/course_structure.rst b/docs/en_us/platform_api/source/course_structure/course_structure.rst index 97bb8a80c3..1c19a1c1c7 100644 --- a/docs/en_us/platform_api/source/course_structure/course_structure.rst +++ b/docs/en_us/platform_api/source/course_structure/course_structure.rst @@ -1,5 +1,5 @@ ######################################## -Course Structure API Module +Course Structure API ######################################## This page contains information on using the Course Structure API to diff --git a/docs/en_us/platform_api/source/enrollment/enrollment.rst b/docs/en_us/platform_api/source/enrollment/enrollment.rst index a83ed87510..5fdd769ba5 100644 --- a/docs/en_us/platform_api/source/enrollment/enrollment.rst +++ b/docs/en_us/platform_api/source/enrollment/enrollment.rst @@ -1,5 +1,5 @@ ################################################## -Enrollment API Module +Enrollment API ################################################## This page contains information on using the Enrollment API to complete diff --git a/docs/en_us/platform_api/source/index.rst b/docs/en_us/platform_api/source/index.rst index 2ff480c77e..fc368fe354 100644 --- a/docs/en_us/platform_api/source/index.rst +++ b/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 - diff --git a/docs/en_us/platform_api/source/mobile/course_info.rst b/docs/en_us/platform_api/source/mobile/course_info.rst index cd0af79f6e..b9c2f700fc 100644 --- a/docs/en_us/platform_api/source/mobile/course_info.rst +++ b/docs/en_us/platform_api/source/mobile/course_info.rst @@ -1,5 +1,5 @@ ################################################## -Mobile Course Information API Module +Mobile Course Information API ################################################## This page describes how to use the Mobile Course Information API diff --git a/docs/en_us/platform_api/source/mobile/users.rst b/docs/en_us/platform_api/source/mobile/users.rst index fc2a7ddafe..37e27ddc76 100644 --- a/docs/en_us/platform_api/source/mobile/users.rst +++ b/docs/en_us/platform_api/source/mobile/users.rst @@ -1,5 +1,5 @@ #################################### -Mobile User API Module +Mobile User API #################################### This page describes how to use the Mobile User API to complete diff --git a/docs/en_us/platform_api/source/mobile/video_outlines.rst b/docs/en_us/platform_api/source/mobile/video_outlines.rst index 1056a7af6d..0f77cff0bb 100644 --- a/docs/en_us/platform_api/source/mobile/video_outlines.rst +++ b/docs/en_us/platform_api/source/mobile/video_outlines.rst @@ -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 diff --git a/docs/en_us/platform_api/source/overview.rst b/docs/en_us/platform_api/source/overview.rst index 57e96de243..b9ca73c990 100644 --- a/docs/en_us/platform_api/source/overview.rst +++ b/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 +`. ********************************************** 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` diff --git a/docs/en_us/platform_api/source/user/accounts.rst b/docs/en_us/platform_api/source/user/accounts.rst index ff2756073a..60d9501e56 100644 --- a/docs/en_us/platform_api/source/user/accounts.rst +++ b/docs/en_us/platform_api/source/user/accounts.rst @@ -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** diff --git a/docs/en_us/platform_api/source/user/endpoints.rst b/docs/en_us/platform_api/source/user/endpoints.rst index a050796366..254766327f 100644 --- a/docs/en_us/platform_api/source/user/endpoints.rst +++ b/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 /api/user/v0/accounts/{username}/[?view=shared] + - GET /api/user/v1/accounts/{username}/[?view=shared] * - :ref:`Update your 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 /api/user/v1/preferences/{username}/ + * - :ref:`Update a user's preferences information ` + - PATCH /api/user/v1/preferences/{username}/ + * - :ref:`Get a specific preference ` + - GET /api/user/v1/preferences/{username}/{preference_key} + * - :ref:`Update a specific preference ` + - PUT /api/user/v1/preferences/{username}/{preference_key} + * - :ref:`Delete a specific preference ` + - DELETE /api/user/v1/preferences/{username}/{preference_key} diff --git a/docs/en_us/platform_api/source/user/index.rst b/docs/en_us/platform_api/source/user/index.rst index aa05686237..97a1bb529a 100644 --- a/docs/en_us/platform_api/source/user/index.rst +++ b/docs/en_us/platform_api/source/user/index.rst @@ -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 diff --git a/docs/en_us/platform_api/source/user/overview.rst b/docs/en_us/platform_api/source/user/overview.rst index b02dbf5a8e..dbda4f7dbb 100644 --- a/docs/en_us/platform_api/source/user/overview.rst +++ b/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 ` +* :ref:`Get and update the user's preferences information ` +* :ref:`Get, update or delete a specific preference: ` diff --git a/docs/en_us/platform_api/source/user/preferences.rst b/docs/en_us/platform_api/source/user/preferences.rst new file mode 100644 index 0000000000..8034555a66 --- /dev/null +++ b/docs/en_us/platform_api/source/user/preferences.rst @@ -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" + diff --git a/openedx/core/djangoapps/user_api/accounts/views.py b/openedx/core/djangoapps/user_api/accounts/views.py index 924e669e22..f7065850bd 100644 --- a/openedx/core/djangoapps/user_api/accounts/views.py +++ b/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. diff --git a/openedx/core/djangoapps/user_api/preferences/views.py b/openedx/core/djangoapps/user_api/preferences/views.py index 8c55ce9de3..7070d20c73 100644 --- a/openedx/core/djangoapps/user_api/preferences/views.py +++ b/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)