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	Supported operations
autoHidePopups	Whether to hide popups (e.g. success messages) after 5 seconds	Boolean	READ / WRITE
notifications	The settings for the notifications to be received by the user	NotificationSetting	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

Methods

Show my preferences

No parameters

200

{
  "_links": {
    "self": {
      "href": "/api/v3/my_preferences"
    },
    "user": {
      "href": "/api/v3/users/1",
      "title": "John Sheppard"
    },
    "updateImmediately": {
      "href": "/api/v3/users/3/preferences",
      "method": "patch"
    }
  },
  "_type": "UserPreferences",
  "commentSortDescending": true,
  "timeZone": "Europe/Berlin",
  "warnOnLeavingUnsaved": true,
  "notifications": {
    "watched": false,
    "involved": true,
    "mentioned": false,
    "shared": true,
    "newsAdded": "false,",
    "newsCommented": false,
    "documentAdded": false,
    "forumMessages": false,
    "wikiPageAdded": false,
    "wikiPageUpdated": false,
    "membershipAdded": false,
    "membershipUpdated": false,
    "workPackageCommented": false,
    "workPackageProcessed": false,
    "workPackagePrioritized": false,
    "workPackageScheduled": false,
    "_links": {
      "project": {
        "href": null
      }
    }
  }
}

UserPreferencesModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/my_preferences"
      },
      "user": {
        "href": "/api/v3/users/1",
        "title": "John Sheppard"
      },
      "updateImmediately": {
        "href": "/api/v3/users/3/preferences",
        "method": "patch"
      }
    },
    "_type": "UserPreferences",
    "commentSortDescending": true,
    "timeZone": "Europe/Berlin",
    "warnOnLeavingUnsaved": true,
    "notifications": [
      {
        "watched": false,
        "involved": true,
        "mentioned": false,
        "shared": true,
        "newsAdded": "false,",
        "newsCommented": false,
        "documentAdded": false,
        "forumMessages": false,
        "wikiPageAdded": false,
        "wikiPageUpdated": false,
        "membershipAdded": false,
        "membershipUpdated": false,
        "workPackageCommented": false,
        "workPackageProcessed": false,
        "workPackagePrioritized": false,
        "workPackageScheduled": false,
        "_links": {
          "project": {
            "href": null
          }
        }
      }
    ]
  }
}

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."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Update my preferences

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

No parameters

Example

{
  "autoHidePopups": true,
  "timeZone": "Europe/Paris"
}

{
  "example": {
    "autoHidePopups": true,
    "timeZone": "Europe/Paris"
  },
  "properties": {
    "autoHidePopups": {
      "type": "boolean"
    },
    "timeZone": {
      "type": "string"
    }
  },
  "type": "object"
}

200

{
  "_links": {
    "self": {
      "href": "/api/v3/my_preferences"
    },
    "user": {
      "href": "/api/v3/users/1",
      "title": "John Sheppard"
    },
    "updateImmediately": {
      "href": "/api/v3/users/3/preferences",
      "method": "patch"
    }
  },
  "_type": "UserPreferences",
  "commentSortDescending": true,
  "timeZone": "Europe/Berlin",
  "warnOnLeavingUnsaved": true,
  "notifications": {
    "watched": false,
    "involved": true,
    "mentioned": false,
    "shared": true,
    "newsAdded": "false,",
    "newsCommented": false,
    "documentAdded": false,
    "forumMessages": false,
    "wikiPageAdded": false,
    "wikiPageUpdated": false,
    "membershipAdded": false,
    "membershipUpdated": false,
    "workPackageCommented": false,
    "workPackageProcessed": false,
    "workPackagePrioritized": false,
    "workPackageScheduled": false,
    "_links": {
      "project": {
        "href": null
      }
    }
  }
}

UserPreferencesModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/my_preferences"
      },
      "user": {
        "href": "/api/v3/users/1",
        "title": "John Sheppard"
      },
      "updateImmediately": {
        "href": "/api/v3/users/3/preferences",
        "method": "patch"
      }
    },
    "_type": "UserPreferences",
    "commentSortDescending": true,
    "timeZone": "Europe/Berlin",
    "warnOnLeavingUnsaved": true,
    "notifications": [
      {
        "watched": false,
        "involved": true,
        "mentioned": false,
        "shared": true,
        "newsAdded": "false,",
        "newsCommented": false,
        "documentAdded": false,
        "forumMessages": false,
        "wikiPageAdded": false,
        "wikiPageUpdated": false,
        "membershipAdded": false,
        "membershipUpdated": false,
        "workPackageCommented": false,
        "workPackageProcessed": false,
        "workPackagePrioritized": false,
        "workPackageScheduled": false,
        "_links": {
          "project": {
            "href": null
          }
        }
      }
    ]
  }
}

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."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

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."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}