API: UserPreferences

The user preferences endpoints return collections or single entities of type UserPreferences. The following tables list the different properties of UserPreferences entities.

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
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

OK

{
  "_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,
  "disableKeyboardShortcuts": false,
  "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,
    "disableKeyboardShortcuts": false,
    "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 
{
  "autoHidePopups": true,
  "timeZone": "Europe/Paris"
}

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

200

OK

{
  "_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,
  "disableKeyboardShortcuts": false,
  "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,
    "disableKeyboardShortcuts": false,
    "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."
    }
  }
}