.. _apis:

API service
===========

Interactions involved
---------------------

Following are the interactions possible with the entities mentioned before
using the API service.

USER
^^^^

Creating new user
"""""""""""""""""

.. image:: ../_static/w2fm_apis_user_post.svg
    :target: ../_images/w2fm_apis_user_post.svg

**PATH** - ``/user/``

**METHOD** - ``POST``

**NOTES**
    - This can be used to create new user entry by filling in the username
      and is auto-triggered when first login is made.
    - The ``username`` and ``password`` provided in the header section must
      belong to a user entry with elevated privileges.

Searching for usernames
"""""""""""""""""""""""

.. image:: ../_static/w2fm_apis_user_get_many.svg
    :target: ../_images/w2fm_apis_user_get_many.svg

**PATH** - ``/user/search``

**METHOD** - ``GET``

**NOTES**
    - This can be used to search for users from the pool of existing users
      depending on the the username provided.
    - The ``username`` and ``password`` provided in the header section must
      belong to an already existing user entry.

Looking up a username
"""""""""""""""""""""

.. image:: ../_static/w2fm_apis_user_get_one.svg
    :target: ../_images/w2fm_apis_user_get_one.svg

**PATH** - ``/user/``

**METHOD** - ``GET``

**NOTES**
    - This can be used to view the details associated with a certain existing
      user entry depending on the username provided.
    - The ``username`` and ``password`` provided in the header section must
      belong to an already existing user entry.

APIKEY
^^^^^^

Creating new access token
"""""""""""""""""""""""""

.. image:: ../_static/w2fm_apis_apikey_post.svg
    :target: ../_images/w2fm_apis_apikey_post.svg

**PATH** - ``/apikey/``

**METHOD** - ``POST``

**NOTES**
    - This can be used to create new access token by filling in the usage
      purpose (optional) and the associated expiry date.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

Listing all access tokens
"""""""""""""""""""""""""

.. image:: ../_static/w2fm_apis_apikey_get_all.svg
    :target: ../_images/w2fm_apis_apikey_get_all.svg

**PATH** - ``/apikey/search``

**METHOD** - ``GET``

**NOTES**
    - This can be used to list all the existing access tokens associated
      with a certain user that those belong to.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

Looking up an access token
""""""""""""""""""""""""""

.. image:: ../_static/w2fm_apis_apikey_get_one.svg
    :target: ../_images/w2fm_apis_apikey_get_one.svg

**PATH** - ``/apikey/``

**METHOD** - ``GET``

**NOTES**
    - This can be used to view the details associated with a certain existing
      access token for the user that it belongs to.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

Revoking an access token
""""""""""""""""""""""""

.. image:: ../_static/w2fm_apis_apikey_put.svg
    :target: ../_images/w2fm_apis_apikey_put.svg

**PATH** - ``/apikey/revoke``

**METHOD** - ``PUT``

**NOTES**
    - This can be used to revoke the validity of an existing access token to
      ensure that the access token can no longer be used.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

SERVICE
^^^^^^^

Creating new service
""""""""""""""""""""

.. image:: ../_static/w2fm_apis_service_post.svg
    :target: ../_images/w2fm_apis_service_post.svg

**PATH** - ``/service/``

**METHOD** - ``POST``

**NOTES**
    - This can be used to create new service by filling in the the message
      topic, message body, service validity and service name.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

Listing all services
""""""""""""""""""""

.. image:: ../_static/w2fm_apis_service_get_all.svg
    :target: ../_images/w2fm_apis_service_get_all.svg

**PATH** - ``/service/search``

**METHOD** - ``GET``

**NOTES**
    - This can be used to list all the existing service entries associated
      with a certain user that those belong to.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

Looking up a service
""""""""""""""""""""

.. image:: ../_static/w2fm_apis_service_get_one.svg
    :target: ../_images/w2fm_apis_service_get_one.svg

**PATH** - ``/service/``

**METHOD** - ``GET``

**NOTES**
    - This can be used to view the details associated with a certain existing
      service for the user that it belongs to.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

Revoking a service
""""""""""""""""""

.. image:: ../_static/w2fm_apis_service_put_revoke.svg
    :target: ../_images/w2fm_apis_service_put_revoke.svg

**PATH** - ``/service/revoke``

**METHOD** - ``PUT``

**NOTES**
    - This can be used to revoke the validity of an existing service to ensure
      that the service can no longer be used.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

Updating a service
""""""""""""""""""

.. image:: ../_static/w2fm_apis_service_put_update.svg
    :target: ../_images/w2fm_apis_service_put_update.svg

**PATH** - ``/service/``

**METHOD** - ``PUT``

**NOTES**
    - This can be used to update the message topic, message body, service
      validity and service name of an existing service.
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.

MESSAGE
^^^^^^^

Invoking an event
"""""""""""""""""

.. image:: ../_static/w2fm_apis_message_post.svg
    :target: ../_images/w2fm_apis_message_post.svg

**PATH** - ``/message/``

**METHOD** - ``POST``

**NOTES**
    - The ``username`` and ``password`` provided in the header section must
      belong to the same ``username`` in the body section.