Specification overview

From RestAuth
Revision as of 16:32, 15 November 2010 by Mati (talk | contribs) (Created page with "The following documentation lists only the status codes returned by the method itself, if you get a response code not listed here, try the [[RestAuth/General response codes|Gener...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to 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 request parameters status codes response body
Create user POST
/users/
user 
The username of the user to create
password 
The password for this 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.
empty
Get list of users GET
/users/
200 Ok 
Always returned
List of usernames
Verify that a user exists GET
/users/<user>/
200 Ok 
If the user exists
404 Not Found 
If the user does not exist
empty
Verify password POST[1]
/users/<user>/
password 
The password to check
200 OK 
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.
empty
Change username/password PUT
/users/<user>/
user 
The username of the user to create
password 
The password for this user
200 OK 
If the credentials where successfully updated
400 Bad Request 
If the new username/password is not acceptable to the system.
404 Not Found 
If the username does not exist
412 Precondition Failed 
If the Service attempts to change the username and the RestAuth instance does not allow such a change[2].
empty
Delete user DELETE
/users/<user>/
200 OK 
If the user really was deleted
404 Not Found 
If the user was not found
empty


  1. 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".
  2. See also the ALLOW_USERNAME_CHANGE

Example commands using curl

Add a new user:

curl -X POST -d 'user=example_user&password=example_pass' -u auth:auth -w "%{http_code}\n" http://auth.example.com/users/

Get a list of users:

curl -u auth:auth http://auth.example.com/users/

Verify that a user exists:

curl -w "%{http_code}\n" -u auth:auth http://auth.example.com/users/example_user/

Verify the password of a user:

curl -X POST -d 'password=example_pass' -u auth:auth -w "%{http_code}\n" http://auth.example.com/users/example_user/

Update password of a user:

curl -X PUT -d 'password=example_pass_new' -u auth:auth -w "%{http_code}\n" http://auth.example.com/users/example_user/

Delete a user:

curl -X DELETE -w "%{http_code}\n" -u auth:auth http://auth.example.com/users/example_user/

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 response body
Get all properties GET /users/<user>/props/
200 OK 
I the request went ok
404 Not Found 
If the user was not found
Dictionary of properties
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
empty
Get a specific 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.
The value of the requested property.
Set/create a property for a user 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
empty
Delete a property DELETE /users/<user>/props/<prop>/
200 OK 
If the resource was deleted
404 Not Found 
If the resource was not found
empty

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 response body
Create 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
empty
Get a list of groups GET
/groups/
user (optional) 
If given, only return groups that the user is a member of
nonrecursive (optional, only with user parameter) 
Do not include parent groups
200 OK 
If no error occured
List of groups
Add user to a group POST
/groups/<group>/ 
user 
The user to add to the named group
autocreate (optional) 
Autocreate the group if it doesn't exist
200 OK 
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 and the autocreate parameter was not given.
empty
Add group to a group POST
/groups/<group>/
group 
The name of the child group to be added to this group
autocreate (optional) 
Automatically create the parent group if it doesn't exist
200 OK 
If the user was successfully added to the group
404 Not Found 
If the child group was not found or if the parent group is not found and the autocreate parameter was not given.
empty
Get all users in a group GET
/groups/<group>/
nonrecursive (optional) 
Do not list users that are member of a parent group
200 Ok 
If the group exists
404 Not Found 
If the group does not exist
List of users
Remove a group DELETE
/groups/<group>/
200 OK 
If the user really was deleted
404 Not Found 
If the group was not found
empty
Check if a user is in a group GET
/groups/<group>/<user>/
nonrecursive (optional) 
Do not check if user is in a parent group
200 Ok 
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.
empty
Remove a user from a group DELETE
/groups/<group>/<user>/
200 OK 
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
empty

Example commands using curl

Create a new group:

curl -X POST -d 'group=example_group' -u auth:auth http://auth.example.com/groups/

Get a list of all groups:

curl -u auth:auth http://auth.example.com/groups/

(note that GET is the default request method)

Get all groups that a user is a member of:

curl -u auth:auth http://auth.example.com/groups/?user=example_user

You may only want to get the groups that a user is a direct member of:

curl -u auth:auth http://auth.example.com/groups/?user=example_user&nonrecursive

Add a user to a group:

curl -X POST -d 'user=example_user' -u auth:auth http://auth.example.com/groups/example_group/

Add a group to a group:

curl -X POST -d 'group=child_group' -u auth:auth http://auth.example.com/groups/parent_group/

In this case, users that are in the parent_group automatically become a member of the child_group.

Get all users in a group:

curl -u auth:auth http://auth.example.com/groups/example_group/

Remove a group:

curl -X DELETE -u auth:auth http://auth.example.com/groups/example_group/

Check if a user is in a group:

curl -u auth:auth http://auth.example.com/groups/example_group/example_user/

Remove a user from a group:

curl -X DELETE -u auth:auth http://auth.example.com/groups/example_group/example_user/