A multipurpose python flask API server and administration SPA
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

273 lines
8.3 KiB

User API
========
.. http:get:: /user
Get a page of users.
**Example request**
.. sourcecode:: http
GET /user HTTP/1.1
Host: example.tld
Accept: application/json
X-Auth-Token: <Base64(user:userToken)>
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"page": 1,
"count": 1,
"totalCount": 1,
"lastPage": 1,
"items": [
{
"creationTime": "2018-07-29T11:58:17-05:00",
"lastLoginTime": "2018-07-29T12:43:27-05:00",
"name": "server_administrator",
"role": "ADMIN",
"version": 0
}
]
}
:query int page: User page to retrieve
:query int perPage: Number of records to retrieve per page (max 100)
:<header Accept: Response content type depends on :mailheader:`Accept` header
:<header X-Auth-Token: Encoded token authorization
:>header Content-Type: Depends on :mailheader:`Accept` header of request
:>json int page: Page retrieved
:>json int count: Number of items returned
:>json int totalCount: Total number of items available
:>json int lastPage: Last page that can be requested before 404
:>json int items: List of Users
:statuscode 200: Successfully retrieved the user
:statuscode 400: Invalid page or perPage values
:statuscode 401: Authorization failed
:statuscode 404: User page doesn't exist
.. http:get:: /user/(str:user_name)
Find a user by name.
**Example request**:
.. sourcecode:: http
GET /user/server_administrator HTTP/1.1
Host: example.tld
Accept: application/json
X-Auth-Token: <Base64(user:userToken)>
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"creationTime": "2018-07-29T11:58:17-05:00",
"lastLoginTime": "2018-07-29T12:43:27-05:00",
"name": "server_administrator",
"role": "ADMIN",
"version": 0
}
:param string user_name: Name of the user to retrieve information about
:<header Accept: Response content type depends on :mailheader:`Accept` header
:<header X-Auth-Token: Encoded token authorization
:>header Content-Type: Depends on :mailheader:`Accept` header of request
:>json datetime creationTime: Creation time for the user
:>json datetime lastLoginTime: When the user last logged in, or was last bumped
:>json string name: The user name
:>json string role: The role assigned to the user
:>json int version: Version information
:statuscode 200: Successfully retrieved the user
:statuscode 401: Authorization failed
:statuscode 404: User doesn't exist
.. http:patch:: /user/(str:user_name)
Patch a user.
**Example request**:
.. sourcecode:: http
PATCH /user/server_administrator HTTP/1.1
Host: example.tld
Accept: application/json
X-Auth-Token: <Base64(user:userToken)>
Content-Type: application/json
{
"lastLoginTime": "2019-07-29T12:43:27-05:00",
"version": 0
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"creationTime": "2018-07-29T11:58:17-05:00",
"lastLoginTime": "2019-07-29T12:43:27-05:00",
"name": "server_administrator",
"role": "ADMIN",
"version": 1
}
:param string user_name: Name of the user to update
:<header Accept: Response content type depends on :mailheader:`Accept` header
:<header X-Auth-Token: Encoded token authorization
:<header Content-Type: application/json
:<json datetime createDateTime: Update createDateTime (Administrator Only)
:<json datetime lastLoginTime: Update lastLoginTime
:<json string name: Update user name (Administrator Only)
:<json string role: Update user role (Must be less than or equal to the role authenticating the action)
:<json int version: Must match the latest version of the user
:>header Content-Type: Depends on :mailheader:`Accept` header of request
:>json datetime creationTime: Creation time for the user
:>json datetime lastLoginTime: When the user last logged in, or was last bumped
:>json string name: The user name
:>json string role: The role assigned to the user
:>json int version: Version information
:statuscode 200: Successfully patched the user
:statuscode 400: An issue in the payload was discovered
:statuscode 401: Authorization failed
:statuscode 404: User doesn't exist
.. http:post:: /user
Register a new user with the service.
**Example request**:
.. sourcecode:: http
POST /user HTTP/1.1
Host: example.tld
Accept: application/json
X-Auth-Token: <Base64(user:userToken)>
Content-Type: application/json
{
"name": "test_user",
"password": "JvZ9bm79",
"role": "USER"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"creationTime": "2018-07-29T14:16:48-05:00",
"name": "test_user",
"role": "USER",
"version": 0
}
:<header Accept: Response content type depends on :mailheader:`Accept` header
:<header X-Auth-Token: Encoded token authorization
:<header Content-Type: application/json
:<json string name: Name of the user
:<json string password: Password to use
:<json string role: Role to assign to the user (Must be less than or equal to the role of the authenticating user)
:>header Content-Type: Depends on :mailheader:`Accept` header of request
:>json datetime creationTime: Datetime the user was created
:>json string name: Name of the created user
:>json string role: Role of the created user
:>json int version: Version number of the created user
:statuscode 200: Successfully registered the user
:statuscode 400: An issue in the payload was discovered
:statuscode 401: Authorization failed
.. http:delete:: /user/(str:user_name)
Register a new user with the service.
**Example request**:
.. sourcecode:: http
DELETE /user/test_user HTTP/1.1
Host: example.tld
Accept: application/json
X-Auth-Token: <Base64(user:userToken)>
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"message": "Successfully Deleted",
"success": true
}
:param string user_name: Name of the user to delete
:<header Accept: Response content type depends on :mailheader:`Accept` header
:<header X-Auth-Token: Encoded token authorization
:>header Content-Type: Depends on :mailheader:`Accept` header of request
:>json string message: Success or failure message
:>json boolean success: Action status indicator
:statuscode 200: Successfully deleted the user
:statuscode 401: Authorization failed
:statuscode 404: User doesn't exist
User Object Models
==================
.. json:object:: Page<User>
:showexample:
Page<User> definition
:property page: The page returned
:proptype page: integer
:property count: The number of items on this page
:proptype count: integer
:property totalCount: The total number of items available
:proptype totalCount: integer
:property lastPage: The last page that is accessible before 404
:proptype lastPage: integer
:property items: The list of items on the page
:proptype items: :json:list: 'User'
.. json:object:: User
:showexample:
User definition
:property name: The unique name of the user
:proptype name: string
:property creationTime: The time that the user was created
:proptype creationTime: iso8601
:property lastLoginTime: The time that the user last logged in
:proptype lastLoginTime: iso8601
:property version: An identifier for the user version
:proptype version: integer
:property role: The assigned role for the user
:proptype role: string