Roles
=================================================

Note: Every endpoint listed in this document is managing JSON objects, so the path structure shown
for nested keys is represented in a JSON-style access pattern.

Root Path: ``/roles/``

Model
------------------------------------------------------

.. list-table:: API endpoint for managing user roles.
   :widths: 15 5 5 75
   :header-rows: 1
   :class: table-striped table-bordered table-hover

   * - Key
     - Type
     - Default
     - Description
   * - role
     - string
     - <colander.required>
     - 
   * - description
     - string
     - 
     - 
   * - allow_all
     - bool
     - false
     - 
   * - permissions
     - []string
     - []
     - 

List
----
Return a list of this collection's items, matching the filter parameters if provided.

HTTP Verb: ``GET``

Endpoint: ``/api/v1/roles/``

Example Request (cURL)::

   curl -X GET -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]"
        -H "Content-Type: application/json"
        https://<yournamehere>.enfixlp.com/api/v1/roles/
        
Example Response::

   [
   {
       "allow_all": false, 
       "role": "Plant Manager", 
       "description": "", 
       "permissions": []
   }
   ]


Get One
-------
Return the specified collection item.

HTTP Verb: ``GET``

Endpoint: ``/api/v1/roles/[id]``

Example Request (cURL)::

   curl -X GET -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]"
        -H "Content-Type: application/json"
        https://<yournamehere>.enfixlp.com/api/v1/roles/[id]
        
Example Response::

   {
       "allow_all": false, 
       "role": "Plant Manager", 
       "description": "", 
       "permissions": []
   }

Create
------
Store a new instance of the object in the system.  All required fields must be specified.

HTTP Verb: ``POST``

Endpoint: ``/api/v1/roles/``

Example Request (cURL)::

   curl -X POST -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]"
        -H "Content-Type: application/json"
        -d '{"allow_all": false, "role": "Plant Manager", "description": "", "permissions": []}'
        https://<yournamehere>.enfixlp.com/api/v1/roles/
        
Example Response::

    {
        "resource_url": "https://<yournamehere>.enfixlp.com/api/v1/roles/51b1e78dbd7a844089b652a9/",
        "_id": "51b1e78dbd7a844089b652a9"
    }

Replace
-------
This is a full model replacement of the specified item, every required field must be specified.

HTTP Verb: ``PUT``

Endpoint: ``/api/v1/roles/[id]``

Example Request (cURL)::

   curl -X PUT -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]"
        -H "Content-Type: application/json"
        -d '{"allow_all": false, "role": "Plant Manager", "description": "", "permissions": []}'
        https://<yournamehere>.enfixlp.com/api/v1/roles/[id]
        
Example Response::

   No body, Status Code 204.

Update
------
On an update, you may specify only the fields you wish to update.  All other fields will be preserved as currently stored.

HTTP Verb: ``PATCH``

Endpoint: ``/api/v1/roles/[id]``

Example Request (cURL)::

   curl -X PUT -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]"
        -H "Content-Type: application/json"
        -d '{"allow_all": false}'
        https://<yournamehere>.enfixlp.com/api/v1/roles/[id]
        
Example Response::

   No body, Status Code 204.

Delete
------
Permanently remove an item from the collection.

HTTP Verb: ``DELETE``

Endpoint: ``/api/v1/roles/[id]``

Example Request (cURL)::

   curl -X DELETE -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]"
        -H "Content-Type: application/json"
        https://<yournamehere>.enfixlp.com/api/v1/roles/[id]
        
Example Response::

   No body, Status Code 200.