Docs for user API
Also some fixes on said API and some fixes in the docs
This commit is contained in:
Gina Häußge
parent
82ae3f6f6e
commit
4e69b260a1
4 changed files with 329 additions and 17 deletions
|
|
@ -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 <sec-api-users-datamodel-userlistresponse>`
|
||||
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 <sec-api-users-datamodel-userrecord>`
|
||||
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 <sec-api-users-datamodel-adduserrequest>`
|
||||
as request body.
|
||||
|
||||
Returns a list of registered users on success, see :ref:`Retrieve a list of users <sec-api-users-list>`.
|
||||
|
||||
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 <sec-api-users-datamodel-updateuserrequest>`
|
||||
as request body.
|
||||
|
||||
Returns a list of registered users on success, see :ref:`Retrieve a list of users <sec-api-users-list>`.
|
||||
|
||||
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 <sec-api-users-list>`.
|
||||
|
||||
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 <sec-api-users-datamodel-userrecord>`
|
||||
- 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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Reference in a new issue