From 937a16e589b6747cf8d495e9f6c6b970846f2611 Mon Sep 17 00:00:00 2001 From: Ben Patterson Date: Mon, 11 May 2015 12:31:38 -0400 Subject: [PATCH] Revert "Adds preferences API and updates users to V1" --- 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, 107 insertions(+), 340 deletions(-) delete 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 d8284b5b9d..6236a10ef2 100644 --- a/docs/en_us/platform_api/source/change_log.rst +++ b/docs/en_us/platform_api/source/change_log.rst @@ -12,11 +12,6 @@ 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 @@ -24,7 +19,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 edX Platform User API - Version 0 sections. + Platform Enrollment API Version 1.0` and :ref:`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 5b3a0ec90a..cffb48a0ad 100644 --- a/docs/en_us/platform_api/source/conf.py +++ b/docs/en_us/platform_api/source/conf.py @@ -170,19 +170,7 @@ MOCK_MODULES = [ 'student.roles', 'embargo.models', 'xmodule.vertical_block', - 'vertical_block', - 'errors', - 'UserNotFound', - 'UserNotAuthorized', - 'AccountUpdateError', - 'AccountValidationError', - 'transaction', - 'parsers', - 'MergePatchParser', - 'get_account_settings', - 'update_account_settings', - 'serializers', - 'PROFILE_IMAGE_KEY_PREFIX' + 'vertical_block' ] 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 31740249ed..d408555943 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 +Course Structure API Module ######################################## 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 5fdd769ba5..a83ed87510 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 +Enrollment API Module ################################################## 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 fc368fe354..2ff480c77e 100644 --- a/docs/en_us/platform_api/source/index.rst +++ b/docs/en_us/platform_api/source/index.rst @@ -24,7 +24,6 @@ Supported APIs enrollment/index mobile/index - user/index ****************** Experimental APIs @@ -34,3 +33,5 @@ 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 b9c2f700fc..cd0af79f6e 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 +Mobile Course Information API Module ################################################## 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 37e27ddc76..fc2a7ddafe 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 +Mobile User API Module #################################### 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 0f77cff0bb..1056a7af6d 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 +Mobile Video Outlines API Module ################################################## 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 b9ca73c990..57e96de243 100644 --- a/docs/en_us/platform_api/source/overview.rst +++ b/docs/en_us/platform_api/source/overview.rst @@ -7,8 +7,7 @@ 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. The APIs also use edX OAuth 2.0 for :ref:`authentication -`. +interchange format. ********************************************** Supported edX Platform API Modules @@ -18,7 +17,6 @@ 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` ********************************************** @@ -28,3 +26,4 @@ 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 60d9501e56..ff2756073a 100644 --- a/docs/en_us/platform_api/source/user/accounts.rst +++ b/docs/en_us/platform_api/source/user/accounts.rst @@ -1,7 +1,5 @@ -.. _User Accounts API: - ################################################## -User Accounts API +User Accounts API Module ################################################## This page contains information on using the User Accounts API to @@ -15,129 +13,7 @@ complete these actions: Get and Update the User's Account Information ********************************************** -.. .. 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. +.. autoclass:: user_api.accounts.views.AccountView **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 254766327f..a050796366 100644 --- a/docs/en_us/platform_api/source/user/endpoints.rst +++ b/docs/en_us/platform_api/source/user/endpoints.rst @@ -15,22 +15,8 @@ The following tasks and endpoints are currently supported. - Use this endpoint: * - :ref:`Get a user's account information ` - - GET /api/user/v1/accounts/{username}/[?view=shared] + - GET /api/user/v0/accounts/{username}/[?view=shared] * - :ref:`Update your account information ` - - 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} + - PATCH /api/user/v0/accounts/{username}/{“key”:”value”} “application + /merge-patch+json” diff --git a/docs/en_us/platform_api/source/user/index.rst b/docs/en_us/platform_api/source/user/index.rst index 97a1bb529a..aa05686237 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 1.0: +.. _edX Platform User API Version 0: ################################# -User API Version 1.0 +User API Version 0 ################################# .. toctree:: @@ -10,4 +10,3 @@ User API Version 1.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 dbda4f7dbb..b02dbf5a8e 100644 --- a/docs/en_us/platform_api/source/user/overview.rst +++ b/docs/en_us/platform_api/source/user/overview.rst @@ -2,17 +2,23 @@ User API Overview ################################################ -Use the User API to view and update account and preference information. +Use the User API to view and update account 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. ************************************* -User API Version 1.0 +EdX Platform User API Version 0 ************************************* -The User API is currently at version 1.0. We plan on making +The User API is currently at version 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 ********************************************** @@ -21,7 +27,3 @@ 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 deleted file mode 100644 index 8034555a66..0000000000 --- a/docs/en_us/platform_api/source/user/preferences.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _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 f7065850bd..924e669e22 100644 --- a/openedx/core/djangoapps/user_api/accounts/views.py +++ b/openedx/core/djangoapps/user_api/accounts/views.py @@ -24,8 +24,7 @@ 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**: @@ -39,74 +38,72 @@ 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: + * gender: One of the following values: + * "m" + * "f" + * "o" + * null - * "m" - * "f" - * "o" - * null + * year_of_birth: The year the user was born, as an integer, or + 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. - * level_of_education: One of the following values: + * language: The user's preferred language, or null. - * "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: null (not set), or a Country corresponding to one of + the ISO 3166-1 countries. - * language: The user's preferred language, or null. + * country: A ISO 3166 country code or null. - * country: null (not set), or a Country corresponding to one of the - ISO 3166-1 countries. + * mailing_address: The textual representation of the user's + mailing address, or null. - * country: A ISO 3166 country code or null. + * goals: The textual representation of the user's goals, or null. - * mailing_address: The textual representation of the user's mailing - address, or null. + * bio: null or textural representation of user biographical + information ("about me"). - * goals: The textual representation of the user's goals, or null. + * is_active: boolean representation of whether a user is active. - * 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. + * 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 @@ -117,8 +114,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 @@ -129,10 +126,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 7070d20c73..8c55ce9de3 100644 --- a/openedx/core/djangoapps/user_api/preferences/views.py +++ b/openedx/core/djangoapps/user_api/preferences/views.py @@ -39,48 +39,30 @@ class PreferencesView(APIView): **Response Value 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 a JSON dictionary with a key/value pair (of type String) - for each preference. + A JSON dictionary will be returned with key/value pairs (all of type String). - The list of preferences depends on your implementation. By default, - preferences include: + If a user without "is_staff" access has requested preferences for a different user, + 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. + If the specified username does not exist, this method returns a 404. **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 users with 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 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) @@ -154,35 +136,30 @@ 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 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 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 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 users with 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 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)