sapi
====

Overview
--------------------------

The Service API requests can be made throught the vanderbilt database
client.

The database has a table named SAPI. The entries correspond to some
actions that can be done on the database. There is a module inside
admintools (sapi.py) that reads these entries and processes them
accordingly. This documentation gives a general overview of how to use
the SAPI requests.

::

   from accre.database import AdminDBClient as DBC

   client = DBC()
   client.add_sapi_request(
       action,
       payload,
       requester,
       ticket=0,
       status='PENDING',
       stage=0,
       creation_time=None,
       modification_time=None    
   )

   :param str action: The SAPI action name for the request, i.e.
       NEWUSER, ADDGROUP, REMOVEGROUP, etc..
   :param str payload: String representing a valid JSON object with
       properties for the action, the contents of the JSON are action
       dependent.
   :param str requester: The staff member or entity requesting the action.
   :param int ticket: The RT ticket number associated with this action. If
       set to 0 (default), a ticket will be generated.
   :param str status: The status code for the new request, defaults to
       pending
   :param int stage: Action-dependent processing stage code, default 0
   :param datetime.datetime creation_time: Time when this request was
       created, if set to None it will be the current time
   :param datetime.datetime modification_time: Time of the last request
       modification, if set to None it will be the current time

   :returns: The SAPI request ID number of the new request
   :rtype: int

Example:

::

   srid = client.add_sapi_request(
       action='NEWUSER',
       payload=json.dumps(data),
       requester=vunetid
   )

Types of SAPI actions
---------------------

-  NEWUSER
-  ADDSGROUP
-  REMSGROUP
-  MODGPFSQUOTA

NEWUSER
-------

Creates a new user with already existing vunetid within the ACCRE
ecosystem.

::

   payload = {
       full_name: "Test",
       vunetid: "vunetid",
       login_group: "group_vunetid",
       email: "email@address.com",
       approved: False/True
   }

If the approved parameter is set to True, it will automatically approve
the user creation. By default it is set to False, that way only after a
PI has approved it, will it be set to True again.

ADDSGROUP
---------

Adds user to a certain group.

::

   payload = {
       vunetid: vunetid of the user (has to be valid and within accre ecosystem)
       group: vunetid of the group
   }

REMSGROUP
---------

Removes user from a certain group

::

   payload = {
       vunetid: vunetid of the user to remove (has to be valid vunetid within accre ecosystem and also withing the group)
       group: vunetid of the group
   }

MODGPFSQUOTA
------------

Modifies the existing GPFS Quota in the database.

::

   payload = {
       fileset (str): Name of the GPFS fileset
       filesystem (str):  Filesystem that the fileset belongs to
       blockquota (str): Soft block quota (should be in units of k, M, G, T, etc..)
       blocklimit (str): Hard block quota/limit (should be in units of k, M, G, T, etc..)
       filequota (str): Soft file quota, or no quota change if None
       filelimit (str): Soft file limit, or no quota change if None
   }


Module Reference
----------------

.. automodule:: accre.sapi
    :members:
    :show-inheritance: