Updating API documentation with json object notation

server/documentation/api/authentication.rst

@@ -29,11 +29,16 @@ Authentication API
         "version": 0
       }
 
-   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
-   :reqheader Authorization: The encoded basic authorization
-   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
-   :statuscode 200: user successfully logged in
-   :statuscode 401: authorization failed
+   :<header Accept: Response content type depends on :mailheader:`Accept` header
+   :<header Authorization: Encoded basic authorization
+   :>header Content-Type: Depends on :mailheader:`Accept` header of request
+   :>json datetime creationTime: Creation time for the userToken
+   :>json datetime expirationTime: Expiration time for the userToken
+   :>json boolean enabled: Whether the userToken is enabled
+   :>json string token: UserToken to use for further authentication
+   :>json int version: Version for the object
+   :statuscode 200: User successfully logged in
+   :statuscode 401: Authorization failed
 
 .. http:post:: /auth/bump
 
@@ -60,11 +65,12 @@ Authentication API
         "lastLoginTime": "2018-07-29T12:15:51-05:00"
       }
 
-   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
-   :reqheader Authorization: The encoded basic authorization
-   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
-   :statuscode 200: user last_login_time successfully bumped
-   :statuscode 401: authorization failed
+   :<header Accept: Response content type depends on :mailheader:`Accept` header
+   :<header Authorization: Encoded token authorization
+   :>header Content-Type: Depends on :mailheader:`Accept` header of request
+   :>json datetime lastLoginTime: Updated lastLoginTime for the user
+   :statuscode 200: User last_login_time successfully bumped
+   :statuscode 401: Authorization failed
 
 .. http:post:: /auth/logout
 
@@ -91,8 +97,9 @@ Authentication API
         "success": true
       }
 
-   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
-   :reqheader Authorization: The encoded basic authorization
-   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
-   :statuscode 200: user successfully logged out
-   :statuscode 401: authorization failed
+   :<header Accept: Response content type depends on :mailheader:`Accept` header
+   :<header Authorization: Rncoded token authorization
+   :>header Content-Type: Depends on :mailheader:`Accept` header of request
+   :>json boolean success: Whether the logout was successful
+   :statuscode 200: User successfully logged out
+   :statuscode 401: Authorization failed

server/documentation/api/user.rst

@@ -30,12 +30,18 @@ User API
         "version": 0
       }
 
-   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
-   :reqheader Authorization: The encoded basic authorization
-   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
-   :statuscode 200: successfully retrieved the user
-   :statuscode 401: authorization failed
-   :statuscode 404: user doesn't exist
+   :param string user_name: Name of the user to retrieve information about
+   :<header Accept: Response content type depends on :mailheader:`Accept` header
+   :<header Authorization: The encoded basic 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)
 
@@ -72,14 +78,25 @@ User API
         "version": 1
       }
 
-   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
-   :reqheader Authorization: The encoded basic authorization
-   :reqheader Content-Type: application/json
-   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
-   :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
+   :param string user_name: Name of the user to update
+   :<header Accept: Response content type depends on :mailheader:`Accept` header
+   :<header Authorization: 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/
 
@@ -116,13 +133,20 @@ User API
         "version": 0
       }
 
-   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
-   :reqheader Authorization: The encoded basic authorization
-   :reqheader Content-Type: application/json
-   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
-   :statuscode 200: successfully registered the user
-   :statuscode 400: an issue in the payload was discovered
-   :statuscode 401: authorization failed
+   :<header Accept: Response content type depends on :mailheader:`Accept` header
+   :<header Authorization: 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)
 
@@ -150,9 +174,12 @@ User API
         "success": true
       }
 
-   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
-   :reqheader Authorization: The encoded basic authorization
-   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
-   :statuscode 200: successfully deleted the user
-   :statuscode 401: authorization failed
-   :statuscode 404: user doesn't exist
+   :param string user_name: Name of the user to delete
+   :<header Accept: Response content type depends on :mailheader:`Accept` header
+   :<header Authorization: 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