diff --git a/docs/api/users.rst b/docs/api/users.rst index d1809258..536c955b 100644 --- a/docs/api/users.rst +++ b/docs/api/users.rst @@ -4,8 +4,311 @@ User **** -.. todo:: - - Needs to be documented - .. contents:: + +.. _sec-api-users-list: + +Retrieve a list of users +======================== + +.. http:get:: /api/users + + Retrieves a list of all registered users in OctoPrint. + + Will return a :http:statuscode:`200` with a :ref:`user list response ` + as body. + + Requires admin rights. + + :status 200: No error + +.. _sec-api-users-retrieve: + +Retrieve a user +=============== + +.. http:get:: /api/users/(string:username) + + Retrieves information about a user. + + Will return a :http:statuscode:`200` with a :ref:`user record ` + as body. + + Requires either admin rights or to be logged in as the user. + + :param username: Name of the user which to retrieve + :status 200: No error + :status 404: Unknown user + +.. _sec-api-users-add: + +Add a user +========== + +.. http:post:: /api/users + + Adds a user to OctoPrint. + + Expects a :ref:`user registration request ` + as request body. + + Returns a list of registered users on success, see :ref:`Retrieve a list of users `. + + Requires admin rights. + + :json name: The user's name + :json password: The user's password + :json active: Whether to activate the account (true) or not (false) + :json admin: Whether to give the account admin rights (true) or not (false) + :status 200: No error + :status 400: If any of the mandatory fields is missing or the request is otherwise + invalid + :status 409: A user with the provided name does already exist + +.. _sec-api-users-update: + +Update a user +============= + +.. http:put:: /api/users/(string:username) + + Updates a user record. + + Expects a :ref:`user update request ` + as request body. + + Returns a list of registered users on success, see :ref:`Retrieve a list of users `. + + Requires admin rights. + + :param username: Name of the user to update + :json admin: Whether to mark the user as admin (true) or not (false), can be left out (no change) + :json active: Whether to mark the account as activated (true) or deactivated (false), can be left out (no change) + :status 200: No error + :status 404: Unknown user + +.. _sec-api-users-delete: + +Delete a user +============= + +.. http:delete:: /api/users/(string:username) + + Delete a user record. + + Returns a list of registered users on success, see :ref:`Retrieve a list of users `. + + Requires admin rights. + + :param username: Name of the user to delete + :status 200: No error + :status 404: Unknown user + +.. _sec-api-users-resetpassword: + +Reset a user's password +======================= + +.. http:put:: /api/users/(string:username)/password + + Changes the password of a user. + + Expects a JSON object with a single property ``password`` as request body. + + Requires admin rights or to be logged in as the user. + + :param username: Name of the user to change the password for + :json password: The new password to set + :status 200: No error + :status 400: If the request doesn't contain a ``password`` property or the request + is otherwise invalid + :status 403: No admin rights and not logged in as the user + :status 404: The user is unknown + +.. _sec-api-users-getsettings: + +Retrieve a user's settings +========================== + +.. http:get:: /api/users/(string:username)/settings + + Retrieves a user's settings. + + Will return a :http:statuscode:`200` with a JSON object representing the user's + personal settings (if any) as body. + + Requires admin rights or to be logged in as the user. + + :param username: Name of the user to retrieve the settings for + :status 200: No error + :status 403: No admin rights and not logged in as the user + :status 404: The user is unknown + +.. _sec-api-users-updatesettings: + +Update a user's settings +======================== + +.. http:patch:: /api/users/(string:username)/settings + + Updates a user's settings. + + Expects a new settings JSON object to merge with the current settings as + request body. + + Requires admin rights or to be logged in as the user. + + :param username: Name of the user to retrieve the settings for + :status 204: No error + :status 403: No admin rights and not logged in as the user + :status 404: The user is unknown + +.. _sec-api-users-generateapikey: + +Regenerate a user's personal API key +==================================== + +.. http:post:: /api/users/(string:username)/apikey + + Generates a new API key for the user. + + Does not expect a body. Will return the generated API key as ``apikey`` + property in the JSON object contained in the response body. + + Requires admin rights or to be logged in as the user. + + :param username: Name of the user to retrieve the settings for + :status 200: No error + :status 403: No admin rights and not logged in as the user + :status 404: The user is unknown + +.. _sec-api-users-deleteapikey: + +Delete a user's personal API key +================================ + +.. http:delete:: /api/users/(string:username)/apikey + + Deletes a user's personal API key. + + Requires admin rights or to be logged in as the user. + + :param username: Name of the user to retrieve the settings for + :status 204: No error + :status 403: No admin rights and not logged in as the user + :status 404: The user is unknown + +.. _sec-api-users-datamodel: + +Data model +========== + +.. _sec-api-users-datamodel-userlistresponse: + +User list response +------------------ + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``users`` + - 0..n + - List of :ref:`user records ` + - The list of registered users + +.. _sec-api-users-datamodel-userrecord: + +User record +----------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``name`` + - 1 + - string + - The user's name + * - ``active`` + - 1 + - bool + - Whether the user's account is active (true) or not (false) + * - ``user`` + - 1 + - bool + - Whether the user has user rights. Should always be true. + * - ``admin`` + - 1 + - bool + - Whether the user has admin rights (true) or not (false) + * - ``apikey`` + - 0..1 + - string + - The user's personal API key + * - ``settings`` + - 1 + - object + - The user's personal settings, might be an empty object. + +.. _sec-api-users-datamodel-adduserrequest: + +User registration request +------------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``name`` + - 1 + - string + - The user's name + * - ``password`` + - 1 + - string + - The user's password + * - ``active`` + - 1 + - bool + - Whether to activate the account (true) or not (false) + * - ``admin`` + - 0..1 + - bool + - Whether to give the user admin rights (true) or not (false or not present) + +.. _sec-api-users-datamodel-updateuserrequest: + +User update request +------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``active`` + - 0..1 + - bool + - If present will set the user's active flag to the provided value. True for + activating the account, false for deactivating it. + * - ``admin`` + - 0..1 + - bool + - If present will set the user's admin flag to the provided value. True for + admin rights, false for no admin rights. diff --git a/docs/api/util.rst b/docs/api/util.rst index 3c3a8d0f..eb50df4b 100644 --- a/docs/api/util.rst +++ b/docs/api/util.rst @@ -19,6 +19,7 @@ Test paths or URLs The following commands are supported at the moment: .. _sec-api-util-test-path: + path Tests whether or provided path exists and optionally if it also is either a file or a directory and whether OctoPrint's user has read, write and/or execute permissions @@ -35,6 +36,7 @@ Test paths or URLs test result! .. _sec-api-util-test-url: + url Tests whether a provided url responds. Request method and expected status codes can optionally be specified as well. Supported parameters are: diff --git a/docs/jsclientlib/timelapse.rst b/docs/jsclientlib/timelapse.rst index 4fdbdbe5..b2879553 100644 --- a/docs/jsclientlib/timelapse.rst +++ b/docs/jsclientlib/timelapse.rst @@ -11,17 +11,17 @@ .. js:function:: OctoPrint.timelapse.list(opts) -.. js:function:: OctoPrint.download(filename, opts) +.. js:function:: OctoPrint.timelapse.download(filename, opts) -.. js:function:: OctoPrint.delete(filename, opts) +.. js:function:: OctoPrint.timelapse.delete(filename, opts) -.. js:function:: OctoPrint.deleteUnrendered(name, opts) +.. js:function:: OctoPrint.timelapse.deleteUnrendered(name, opts) -.. js:function:: OctoPrint.renderUnrendered(name, opts) +.. js:function:: OctoPrint.timelapse.renderUnrendered(name, opts) -.. js:function:: getConfig(opts) +.. js:function:: OctoPrint.timelapse.getConfig(opts) -.. js:function:: saveConfig(config, opts) +.. js:function:: OctoPrint.timelapse.saveConfig(config, opts) .. seealso:: diff --git a/src/octoprint/server/api/users.py b/src/octoprint/server/api/users.py index e2f1fe05..73233f5e 100644 --- a/src/octoprint/server/api/users.py +++ b/src/octoprint/server/api/users.py @@ -12,7 +12,7 @@ from flask.ext.login import current_user import octoprint.users as users from octoprint.server import SUCCESS, admin_permission, userManager -from octoprint.server.api import api +from octoprint.server.api import api, valid_boolean_trues from octoprint.server.util.flask import restricted_access @@ -44,12 +44,19 @@ def addUser(): except BadRequest: return make_response("Malformed JSON body in request", 400) + if not "name" in data: + return make_response("Missing mandatory name field", 400) + if not "password" in data: + return make_response("Missing mandatory password field", 400) + if not "active" in data: + return make_response("Missing mandatory active field", 400) + name = data["name"] password = data["password"] - active = data["active"] + active = data["active"] in valid_boolean_trues roles = ["user"] - if "admin" in data.keys() and data["admin"]: + if "admin" in data and data["admin"] in valid_boolean_trues: roles.append("admin") try: @@ -94,13 +101,13 @@ def updateUser(username): # change roles roles = ["user"] - if "admin" in data.keys() and data["admin"]: + if "admin" in data and data["admin"] in valid_boolean_trues: roles.append("admin") userManager.changeUserRoles(username, roles) # change activation - if "active" in data.keys(): - userManager.changeUserActivation(username, data["active"]) + if "active" in data: + userManager.changeUserActivation(username, data["active"] in valid_boolean_trues) return getUsers() else: abort(404) @@ -135,7 +142,7 @@ def changePasswordForUser(username): except BadRequest: return make_response("Malformed JSON body in request", 400) - if not "password" in data.keys() or not data["password"]: + if not "password" in data or not data["password"]: return make_response("password is missing from request", 400) try: