mirror of https://gitee.com/bigwinds/arangodb
310 lines
8.8 KiB
Plaintext
310 lines
8.8 KiB
Plaintext
!CHAPTER HTTP Interface for User Management
|
|
|
|
@NAVIGATE_HttpUser
|
|
@EMBEDTOC{HttpUserTOC}
|
|
|
|
!SUBSECTION User Management
|
|
|
|
This is an introduction to ArangoDB's Http interface for managing users.
|
|
|
|
The interface provides a simple means to add, update, and remove users. All
|
|
users managed through this interface will be stored in the system collection
|
|
`_users`.
|
|
|
|
This specialized interface intentionally does not provide all functionality that
|
|
is available in the regular document REST API.
|
|
|
|
Operations on users may become more restricted than regular document operations,
|
|
and extra privileges and security security checks may be introduced in the
|
|
future for this interface.
|
|
|
|
Please note that user operations are not included in ArangoDB's replication.
|
|
|
|
@COMMENT{######################################################################}
|
|
@anchor HttpUserSave
|
|
@RESTHEADER{POST /_api/user,creates user}
|
|
|
|
@RESTBODYPARAM{body,json,required}
|
|
|
|
@RESTDESCRIPTION
|
|
|
|
The following data need to be passed in a JSON representation in the body of the
|
|
POST request:
|
|
|
|
- `user`: The name of the user as a string. This is mandatory.
|
|
|
|
- `passwd`: The user password as a string. If no password is specified, the
|
|
empty string will be used.
|
|
|
|
- `active`: an optional flag that specifies whether the user is active. If not
|
|
specified, this will default to `true`.
|
|
|
|
- `extra`: an optional JSON object with arbitrary extra data about the user.
|
|
|
|
- `changePassword`: an optional flag that specifies whethers the user must
|
|
change the password or not. If not specified, this will default to `false`.
|
|
|
|
If set to `true`, the only operations allowed are `PUT /_api/user` or
|
|
`PATCH /_api/user`. All other operations will result in a `HTTP 403`.
|
|
|
|
If the user can be added by the server, the server will respond with `HTTP 201`.
|
|
|
|
In case of success, the returned JSON object has the following properties:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`false` in this
|
|
case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
If the JSON representation is malformed or mandatory data is missing from the
|
|
request, the server will respond with `HTTP 400`.
|
|
|
|
The body of the response will contain a JSON object with additional error
|
|
details. The object has the following attributes:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`true` in this case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
- `errorNum`: the server error number
|
|
|
|
- `errorMessage`: a descriptive error message
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{201}
|
|
returned if the user can be added by the server.
|
|
|
|
@RESTRETURNCODE{400}
|
|
If the JSON representation is malformed or mandatory data is missing from the
|
|
request.
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpUserReplace
|
|
@RESTHEADER{PUT /_api/user/{user},replaces user}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{user,string,required}
|
|
The name of the user.
|
|
|
|
@RESTBODYPARAM{body,json,required}
|
|
|
|
@RESTDESCRIPTION
|
|
|
|
Replaces the data of an existing user. The name of an existing user must be
|
|
specified in `user`.
|
|
|
|
The following data can to be passed in a JSON representation in the body of the
|
|
POST request:
|
|
|
|
- `passwd`: The user password as a string. Specifying a password is mandatory,
|
|
but the empty string is allowed for passwords.
|
|
|
|
- `active`: an optional flag that specifies whether the user is active. If not
|
|
specified, this will default to `true`.
|
|
|
|
- `extra`: an optional JSON object with arbitrary extra data about the user.
|
|
|
|
- `changePassword`: an optional flag that specifies whether the user must change
|
|
the password or not. If not specified, this will default to `false`.
|
|
|
|
If the user can be replaced by the server, the server will respond with `HTTP
|
|
200`.
|
|
|
|
In case of success, the returned JSON object has the following properties:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`false` in this
|
|
case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
If the JSON representation is malformed or mandatory data is missing from the
|
|
request, the server will respond with `HTTP 400`. If the specified user does not
|
|
exist, the server will respond with `HTTP 404`.
|
|
|
|
The body of the response will contain a JSON object with additional error
|
|
details. The object has the following attributes:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`true` in this case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
- `errorNum`: the server error number
|
|
|
|
- `errorMessage`: a descriptive error message
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{200}
|
|
Is returned if the user data can be replaced by the server.
|
|
|
|
@RESTRETURNCODE{400}
|
|
The JSON representation is malformed or mandatory data is missing from the
|
|
request.
|
|
|
|
@RESTRETURNCODE{404}
|
|
The specified user does not exist.
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpUserUpdate
|
|
@RESTHEADER{PATCH /_api/user/{user},updates user}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{user,string,required}
|
|
The name of the user.
|
|
|
|
@RESTBODYPARAM{body,json,required}
|
|
|
|
@RESTDESCRIPTION
|
|
|
|
Partially updates the data of an existing user. The name of an existing user
|
|
must be specified in `user`.
|
|
|
|
The following data can be passed in a JSON representation in the body of the
|
|
POST request:
|
|
|
|
- `passwd`: The user password as a string. Specifying a password is optional. If
|
|
not specified, the previously existing value will not be modified.
|
|
|
|
- `active`: an optional flag that specifies whether the user is active. If not
|
|
specified, the previously existing value will not be modified.
|
|
|
|
- `extra`: an optional JSON object with arbitrary extra data about the user. If
|
|
not specified, the previously existing value will not be modified.
|
|
|
|
- `changePassword`: an optional flag that specifies whether the user must change
|
|
the password or not. If not specified, the previously existing value will not
|
|
be modified.
|
|
|
|
If the user can be updated by the server, the server will respond with `HTTP
|
|
200`.
|
|
|
|
In case of success, the returned JSON object has the following properties:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`false` in this
|
|
case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
If the JSON representation is malformed or mandatory data is missing from the
|
|
request, the server will respond with `HTTP 400`. If the specified user does not
|
|
exist, the server will respond with `HTTP 404`.
|
|
|
|
The body of the response will contain a JSON object with additional error
|
|
details. The object has the following attributes:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`true` in this case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
- `errorNum`: the server error number
|
|
|
|
- `errorMessage`: a descriptive error message
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{200}
|
|
Is returned if the user data can be replaced by the server.
|
|
|
|
@RESTRETURNCODE{400}
|
|
The JSON representation is malformed or mandatory data is missing from the
|
|
request.
|
|
|
|
@RESTRETURNCODE{404}
|
|
The specified user does not exist.
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpUserRemove
|
|
@RESTHEADER{DELETE /_api/user/{user},removes a user}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{user,string,required}
|
|
The name of the user.
|
|
|
|
@RESTDESCRIPTION
|
|
|
|
Removes an existing user, identified by `user`.
|
|
|
|
If the user can be removed, the server will respond with `HTTP 202`.
|
|
|
|
In case of success, the returned JSON object has the following properties:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`false` in this
|
|
case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
If the specified user does not exist, the server will respond with `HTTP 404`.
|
|
|
|
The body of the response will contain a JSON object with additional error
|
|
details. The object has the following attributes:
|
|
|
|
- `error`: boolean flag to indicate that an error occurred (`true` in this case)
|
|
|
|
- `code`: the HTTP status code
|
|
|
|
- `errorNum`: the server error number
|
|
|
|
- `errorMessage`: a descriptive error message
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{202}
|
|
Is returned if the user was removed by the server.
|
|
|
|
@RESTRETURNCODE{404}
|
|
The specified user does not exist.
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@CLEARPAGE
|
|
@anchor HttpUserDocument
|
|
@RESTHEADER{GET /_api/user/{user},fetches a user}
|
|
|
|
@RESTURLPARAMETERS
|
|
|
|
@RESTURLPARAM{user,string,required}
|
|
The name of the user.
|
|
|
|
@RESTDESCRIPTION
|
|
|
|
Fetches data about the specified user.
|
|
|
|
The call will return a JSON document with at least the following attributes on
|
|
success:
|
|
|
|
- `user`: The name of the user as a string.
|
|
|
|
- `active`: an optional flag that specifies whether the user is active.
|
|
|
|
- `extra`: an optional JSON object with arbitrary extra data about the user.
|
|
|
|
- `changePassword`: an optional flag that specifies whether the user must change
|
|
the password or not.
|
|
|
|
@RESTRETURNCODES
|
|
|
|
@RESTRETURNCODE{200}
|
|
The user was found.
|
|
|
|
@RESTRETURNCODE{404}
|
|
The user with `user` does not exist.
|
|
|
|
@RESTDONE
|
|
|
|
@COMMENT{######################################################################}
|
|
@BNAVIGATE_HttpUser
|