API: UserPreferences

Linked Properties

Link Description Type Constraints Supported operations
self This UserPreferences UserPreferences not null READ
user The user that this preference belongs to User not null READ

Local Properties

Property Description Type Constraints Supported operations
hideMail Hide mail address from other users Boolean   READ / WRITE
timeZone Current selected time zone String   READ / WRITE
commentSortDescending Sort comments in descending order Boolean   READ / WRITE
warnOnLeavingUnsaved Issue warning when leaving a page with unsaved text Boolean   READ / WRITE
accessibilityMode Enable accessibility mode Boolean   READ / WRITE

Methods

Show my preferences

No parameters

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/my_preferences"
    },
    "user": {
      "href": "/api/v3/users/1",
      "title": "John Sheppard"
    }
  },
  "_type": "UserPreferences",
  "accessibilityMode": false,
  "commentSortDescending": true,
  "hideMail": false,
  "timeZone": "Europe/Berlin",
  "warnOnLeavingUnsaved": true
}

UserPreferencesModel

{
  "type": "object",
  "example": {
    "_type": "UserPreferences",
    "_links": {
      "self": {
        "href": "/api/v3/my_preferences"
      },
      "user": {
        "href": "/api/v3/users/1",
        "title": "John Sheppard"
      }
    },
    "hideMail": false,
    "timeZone": "Europe/Berlin",
    "commentSortDescending": true,
    "warnOnLeavingUnsaved": true,
    "accessibilityMode": false
  }
}

401

Returned if no user is currently authenticated

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}

Update userpreferences

When calling this endpoint the client provides a single object, containing the properties that it wants to change, in the body.

No parameters

{
  "accessibilityMode": true,
  "timeZone": "Europe/Paris"
}
{
  "accessibilityMode": {
    "type": "boolean"
  },
  "timeZone": {
    "type": "string"
  }
}

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/my_preferences"
    },
    "user": {
      "href": "/api/v3/users/1",
      "title": "John Sheppard"
    }
  },
  "_type": "UserPreferences",
  "accessibilityMode": false,
  "commentSortDescending": true,
  "hideMail": false,
  "timeZone": "Europe/Berlin",
  "warnOnLeavingUnsaved": true
}

UserPreferencesModel

{
  "type": "object",
  "example": {
    "_type": "UserPreferences",
    "_links": {
      "self": {
        "href": "/api/v3/my_preferences"
      },
      "user": {
        "href": "/api/v3/users/1",
        "title": "John Sheppard"
      }
    },
    "hideMail": false,
    "timeZone": "Europe/Berlin",
    "commentSortDescending": true,
    "warnOnLeavingUnsaved": true,
    "accessibilityMode": false
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

401

Returned if no user is currently authenticated

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}

422

Returned if the update contains invalid properties. Reasons are:

  • Specifying an invalid type

  • Using an unknown time zone

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Time zone is not set to one of the allowed values."
}