Specification overview

From RestAuth
Jump to: navigation, search

The following documentation lists only the status codes returned by the method itself, if you get a response code not listed here, try the General response codes page.

Basic user management

Basic user management takes care of the very basic functionalities related to user management. It allows you to get a list of users, add a user to the system, set/verify the password and delete a user. The basic user management facilities provided by RestAuth are as simple as in any way possible. For all important operations you only have to check the status code returned to get the answer to your question - there is no need to parse the response body at all. The only exception to this is getting a list of all known users.


what method URI parameters notable status codes
Create a user POST
/users/
user 
The username of the user to create
password 
Optional. The password for this user. If not set or set to an empty value, the user has no password.
properties 
Optional. Initial properties for the new user.
groups 
Optional. Initial groups for the new user.
201 Created 
If the creation of the user succeeded
409 Conflict 
If the user already exists
412 Precondition Failed 
If the submitted username or password is not acceptable to the system. See also: Restriction on entity names.
Get a list of users GET
/users/
200 Ok 
Always returned
Verify that a user exists GET
/users/<user>/
200 Ok 
If the user exists
404 Not Found 
If the user does not exist
Verify password POST<ref>Following the REST paradigm, this really should be a GET request, not a POST request. GET requests have one major disadvantage, though: GET parameters are usually logged in the log-files of your webserver. This would mean that a password verification request to users/<username>?password=<password> would be logged. There are ways around logging this, but in our opinion services should always be "secure by default".</ref>
/users/<user>/
password 
The password to check
groups 
Optional. A list of groups that the user has to be a member of
204 No Content 
If the given password is the right one for the given user
404 Not Found 
If the user is not found or if the password does not match.
Change password PUT
/users/<user>/
password 
Optional. The new password for this user. If not set or set to an empty value, the user has no password.
204 No Content 
If the password was successfully updated
404 Not Found 
If the username does not exist
412 Precondition Failed 
If the new username or password is not acceptable to the system. See also: Restriction on entity names.
Delete a user DELETE
/users/<user>/
204 No Content 
If the user really was deleted
404 Not Found 
If the user was not found

<references />

Managing user properties

It is possible to use RestAuth to store user properties like email-addresses, real names, etc. The keys that applications use for certain properties is by convention only, so applications have to take care to map their internal names for a property to the name RestAuth knows about.

what method request parameters status codes
Get all properties GET
/users/<user>/props/
200 OK 
I the request went ok
404 Not Found 
If the user was not found
Create a new property POST
/users/<user>/props/
prop 
The name of the property to set
value 
The value of the property
200 OK 
If the property was successfully set
404 Not Found 
If the user does not exist.
409 Conflict 
If the resource already existed
Set values of multiple properties PUT
/users/<user>/props/
A dictionary of key/value pairs of properties to set.
200 OK 
If the properties were set.
404 Not Found 
If the user doesn't exist.
Get value of a property GET
/users/<user>/props/<prop>/
200 OK 
If the user and the specified property exists
404 Not Found 
If either the user or the property does not exist.
Set value of a property PUT
/users/<user>/props/<prop>/
value 
The (new) value of the addressed property
200 OK 
If the property was set, regardless if it previously existed or not.
404 Not Found 
If the user was not found
Delete a property DELETE
/users/<user>/props/<prop>/
200 OK 
If the resource was deleted
404 Not Found 
If the resource was not found

Group management

Many systems use a group based model to manage privileges granted to individual users. You can use RestAuth to manage the groups that a user is in. Services always only have access to their own set of groups, so e.g. becoming administrator in one service does not make you administrator in any other service. It is however possible to inherit group membership from other groups, that are not necessarily associated with any service. So you could define an 'admin' group and define that the admin group of every service inherits its members from that general group. It is not possible for a service to manage groups outside of its own scope, including groups not associated with any service.

what method request parameters status codes
Get a list of groups GET
/groups/
user (optional) 
If given, only return groups that the user is a member of
200 OK 
If no error occured
Create a group POST
/groups/
group 
name of the group to create
201 Created 
If the group was successfully created
409 Conflict 
If the group already exists
Set groups of a user PUT
/groups/
user 
Name of the user to set the groups for
groups 
List of new groups for the user
204 No content 
If the operation was successful
404 Not Found
I f the user does not exist
Verify that a group exists GET
/groups/<group>/
204 No Content 
If the group exists
404 Not Found 
If the group does not exist
Delete a group DELETE
/groups/<group>/
204 No Content 
If the group was removed.
404 Not Found 
If the group was not found.
Get all users in a group GET
/groups/<group>/users/
200 Ok 
If the group exists
404 Not Found 
If the group does not exist
Add a user to a group POST
/groups/<group>/users/
user 
The user to add to the named group
204 No Content 
If the user was successfully added to the group
404 Not Found 
If the user was not found or if the group is not found.
Set users of a group PUT
/groups/<group>/users/
users 
The new users of a group
204 No Content 
If the list of users users was successfully set
404 Not Found 
If the group was not found or any of the given users is not found.
Verify that a user is in a group GET
/groups/<group>/users/<user>/
204 No Content 
If the user is in the group.
404 Not Found 
If either group or user does not exist or if the user is not in the group. In the latter case, the response will not contain a body.
Remove a user from a group DELETE
/groups/<group>/users/<user>/
204 No Content 
If the user was removed from the group or the user was not in the group
404 Not Found 
If the group or the user do not exist
Get a list of sub-groups GET
/groups/<group>/groups/
200 Ok 
If no error occured.
404 Not Found 
If the group does not exist.
Add a group to a group POST
/groups/<group>/groups/
group 
The name of the child group to be added to this group
204 No Content 
If no error occured.
404 Not Found 
If the child group was not found or if the parent group is not found.
Set subgroups of a group PUT
/groups/<group>/groups/
groups 
The new groups of a group
204 No Content 
If the list of groups users was successfully set
404 Not Found 
If the group was not found or any of the given subgroups is not found.
Verify that a group is in a group GET
/groups/<group>/groups/<subgroup>/
204 No Content 
If the group is in the group.
404 Not Found 
If either group or group does not exist or if the subgroup is not in the group. In the latter case, the response will not contain a body.
Remove a group from a group DELETE
/groups/<group>/groups/<subgroup>/
204 No Content 
If the user really was deleted
404 Not Found 
If the group was not found

Dry-Runs

See Doing dry-runs.