RestAuth/Specification overview: Unterschied zwischen den Versionen

Aus Free Software
Zur Navigation springen Zur Suche springen
(Änderung 3442 von Mati (Diskussion) rückgängig gemacht.)
 
Zeile 1: Zeile 1:
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|General response codes]] page.
+
#REDIRECT [[https://restauth.net/wiki/Specification_overview]]
 
 
= 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.
 
 
 
 
 
{|border="1"
 
! what !! method !! request !! parameters !! status codes !! response body
 
|-
 
| Create user || POST || <pre>/users/</pre> ||
 
; 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 || <pre>/users/</pre> || ||
 
; 200 Ok : Always returned
 
| List of usernames
 
|-
 
| Verify that a user exists || GET || <pre>/users/<user>/</pre> || ||
 
; 200 Ok : If the user exists
 
; 404 Not Found : If the user does not exist
 
| empty
 
|-
 
| 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> || <pre>/users/<user>/</pre> ||
 
; 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 || <pre>/users/<user>/</pre> ||
 
; password : The password for this user
 
|
 
; 200 OK : If the credentials where successfully updated
 
; 400 Bad Request :
 
; 404 Not Found : If the username does not exist
 
; 412 Precondition Failed : If the new username or password is not acceptable to the system.
 
| empty
 
|-
 
| Delete user || DELETE || <pre>/users/<user>/</pre> || ||
 
; 200 OK : If the user really was deleted
 
; 404 Not Found : If the user was not found
 
| empty
 
|}
 
 
 
 
 
<references />
 
 
 
==== Example commands using curl ====
 
'''Add a new user:'''
 
<nowiki>curl -X POST -d 'user=example_user&password=example_pass' -u auth:auth -w "%{http_code}\n" http://auth.example.com/users/</nowiki>
 
'''Get a list of users:'''
 
<nowiki>curl -u auth:auth http://auth.example.com/users/</nowiki>
 
'''Verify that a user exists:'''
 
<nowiki>curl -w "%{http_code}\n" -u auth:auth http://auth.example.com/users/example_user/</nowiki>
 
'''Verify the password of a user:'''
 
<nowiki>curl -X POST -d 'password=example_pass' -u auth:auth -w "%{http_code}\n" http://auth.example.com/users/example_user/</nowiki>
 
'''Update password of a user:'''
 
<nowiki>curl -X PUT -d 'password=example_pass_new' -u auth:auth -w "%{http_code}\n" http://auth.example.com/users/example_user/</nowiki>
 
'''Delete a user:'''
 
<nowiki>curl -X DELETE -w "%{http_code}\n" -u auth:auth http://auth.example.com/users/example_user/</nowiki>
 
 
 
= 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.
 
 
 
{|border="1"
 
! 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.
 
 
 
{|border="1"
 
! what !! method !! request !! parameters !! status codes !! response body
 
|-
 
| Create group || POST || <pre>/groups/</pre>
 
|
 
; 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 || <pre>/groups/</pre>
 
|
 
; 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 || <pre>/groups/<group>/ </pre>
 
|
 
; 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 || <pre>/groups/<group>/</pre>
 
|
 
; 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 || <pre>/groups/<group>/</pre>
 
|
 
; 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 || <pre>/groups/<group>/</pre> || || |
 
; 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 || <pre>/groups/<group>/<user>/</pre>
 
|
 
; 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 || <pre>/groups/<group>/<user>/</pre> || || |
 
; 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:'''
 
<nowiki>curl -X POST -d 'group=example_group' -u auth:auth http://auth.example.com/groups/</nowiki>
 
 
 
'''Get a list of all groups:'''
 
<nowiki>curl -u auth:auth http://auth.example.com/groups/</nowiki>
 
(note that GET is the default request method)
 
 
 
'''Get all groups that a user is a member of:'''
 
<nowiki>curl -u auth:auth http://auth.example.com/groups/?user=example_user</nowiki>
 
 
 
You may only want to get the groups that a user is a direct member of:
 
<nowiki>curl -u auth:auth http://auth.example.com/groups/?user=example_user&nonrecursive</nowiki>
 
 
 
'''Add a user to a group:'''
 
<nowiki>curl -X POST -d 'user=example_user' -u auth:auth http://auth.example.com/groups/example_group/</nowiki>
 
 
 
'''Add a group to a group:'''
 
<nowiki>curl -X POST -d 'group=child_group' -u auth:auth http://auth.example.com/groups/parent_group/</nowiki>
 
In this case, users that are in the ''parent_group'' automatically become a member of the ''child_group''.
 
 
 
'''Get all users in a group:'''
 
<nowiki>curl -u auth:auth http://auth.example.com/groups/example_group/</nowiki>
 
 
 
'''Remove a group:'''
 
<nowiki>curl -X DELETE -u auth:auth http://auth.example.com/groups/example_group/</nowiki>
 
 
 
'''Check if a user is in a group:'''
 
<nowiki>curl -u auth:auth http://auth.example.com/groups/example_group/example_user/</nowiki>
 
 
 
'''Remove a user from a group:'''
 
<nowiki>curl -X DELETE -u auth:auth http://auth.example.com/groups/example_group/example_user/</nowiki>
 

Aktuelle Version vom 10. September 2011, 18:21 Uhr