User API User Preferences Resource

With the User API User Preferences resource, you can complete the following tasks.

Get and Update the User’s Preferences Information

class user_api.preferences.views.PreferencesView(**kwargs)

Use Cases

Get or update the user’s preference information. Updates are only supported through merge patch. Preference values of null in a patch request are treated as requests to remove the preference.

Example Requests

GET /api/user/v1/preferences/{username}/

PATCH /api/user/v1/preferences/{username}/ with content_type “application/merge-patch+json”

Response Values for GET

If no user exists with the specified username, an HTTP 404 “Not Found” response is returned.

If a user without “is_staff” access requests preferences for a different user, an HTTP 404 “Not Found” message is returned.

If the user makes the request for her own account, or makes a request for another account and has “is_staff” access, an HTTP 200 “OK” response is returned. The response contains a JSON dictionary with a key/value pair (of type String) for each preference.

The list of preferences depends on your implementation. By default, the list includes the following preferences.

• account_privacy: The user’s setting for sharing her personal profile. Possible values are “all_users” or “private”.
• pref-lan: The user’s preferred language, as set in account settings.

Response Values for PATCH

Users can only modify their own preferences. If the requesting user does not have the specified username and has staff access, the request returns an HTTP 403 “Forbidden” response. If the requesting user does not have staff access, the request returns an HTTP 404 “Not Found” response to avoid revealing the existence of the account.

If no user exists with the specified username, an HTTP 404 “Not Found” response is returned.

If “application/merge-patch+json” is not the specified content type, a 415 “Unsupported Media Type” response is returned.

If validation errors prevent the update, this method returns a 400 “Bad Request” response that includes a “field_errors” field that lists all error messages.

If a failure at the time of the update prevents the update, a 400 “Bad Request” error is returned. The JSON collection contains specific errors.

If the update is successful, an HTTP 204 “No Content” response is returned with no additional content.

Example response showing the user’s preference information

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

class user_api.preferences.views.PreferencesDetailView(**kwargs)

Use Cases

Get, create, update, or delete a specific user preference.

Example Requests

GET /api/user/v1/preferences/{username}/{preference_key}

PUT /api/user/v1/preferences/{username}/{preference_key}

DELETE /api/user/v1/preferences/{username}/{preference_key}

Response Values for GET

If the specified username or preference does not exist, an HTTP 404 “Not Found” response is returned.

If a user without “is_staff” access requests preferences for a different user, a 404 error is returned.

If the user makes the request for her own account, or makes a request for another account and has “is_staff” access, an HTTP 200 “OK” response is returned that contains a JSON string.

Response Values for PUT

Users can only modify their own preferences. If the requesting user does not have the specified username and has staff access, the request returns an HTTP 403 “Forbidden” response. If the requesting user does not have staff access, the request returns an HTTP 404 “Not Found” response to avoid revealing the existence of the account.

If the specified preference does not exist, an HTTP 404 “Not Found” response is returned.

If the request is successful, a 204 “No Content” status is returned with no additional content.

Response Values for DELETE

Users can only delete their own preferences. If the requesting user does not have the specified username and has staff access, the request returns an HTTP 403 “Forbidden” response. If the requesting user does not have staff access, the request returns an HTTP 404 “Not Found” response to avoid revealing the existence of the account.

If the specified preference does not exist, an HTTP 404 “Not Found” response is returned.

If the update is successful, an HTTP 204 “No Content” response is returned with no additional content.

Example response to a request for the user’s account_privacy setting

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS, PATCH

"private"