229 lines
6.1 KiB
ReStructuredText
229 lines
6.1 KiB
ReStructuredText
|
.. _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.
|