===============
API Description
===============

URL
===

The root URL of the API is build following the following schema.

``https://<appplatform>/<domain>/<instance>/api``

For example:

``https://apps.company.com/company.com/myinstance1/api``


Authorization
=============

A header is used in HTTP requests to provide authentication credentials.
In our case, we will be using a bearer token for this purpose. 
The header must be included in every request sent to the protected API endpoints.

The bearertoken can be modified via the admin app settings form.


Endpoints
=========

/groups GET
-----------

Returns a list of the current groups and their members.

.. code-block::

  curl 'https://apps.example.com/example.com/grpapi1/api/groups' \
    -H 'Authorization: Bearer 98ms098sm09s8ms098sm09s8m' \
    -X 'GET'

.. code-block::

  {
    "Gruppe1": {
      "name": "Gruppe1",
      "pbx": "pbx-main",
      "members": {
        "7a33480adef46101472e009033400109": {
          "guid": "7a33480adef46101472e009033400109",
          ...
        },
        "7a33480asef46101472e009033400109": {
          "guid": "7a33480asef46101472e009033400109",
          ...
        }
      }
    },
    "Gruppe2": {
      "name": "Gruppe2",
      "pbx": "pbx-main",
      "members": {
        ...
      }
    }, ...
  }


/groups POST
------------

Add, change or delete Group Memberships of Pbxobjects with HTTP ``POST`` request.

The POST request must contain a valid ``JSON`` formated message.

The keys that must be present in each request are the following:

+--------+---------------------------------------------+
| Key    | Value                                       |
+--------+---------------------------------------------+
| cn     | the common name of the pbx object to change |
+--------+---------------------------------------------+
| grp    | the name of the group to be changed         |
+--------+---------------------------------------------+
| action | 0=delete, 1=add or change                   |
+--------+---------------------------------------------+
| state  | (optional) 0=static*, 1=dyn-in, 2=dyn-out   |
+--------+---------------------------------------------+
| active | (optional) 0=not active*, 1=active          |
+--------+---------------------------------------------+

As example a curl request to add a User ``testcaller5`` to the new group ``TestGroup1`` as ``dyn-in`` as ``active``.

.. code-block::

  curl 'https://apps.example.com/example.com/grpapi1/api/groups' \
    -H 'Authorization: Bearer 98ms098sm09s8ms098sm09s8m' \
    -X 'POST' \
    -d '{
        "cn": "testcaller5",
        "grp": "TestGroup1",
        "action": 1,
        "state": 1,
        "active": 1
    }'

To remove a User from a group the message would contain ``action: 0``:

.. code-block::

  curl 'https://apps.example.com/example.com/grpapi1/api/groups' \
    -H 'Authorization: Bearer 98ms098sm09s8ms098sm09s8m' \
    -X 'POST' \
    -d '{
        "cn": "testcaller5",
        "grp": "TestGroup1",
        "action": 0
    }'

/pbx POST
---------

Provides generic access to the PbxAdminApi as documented at the `innovaphone SDK docs/ PbxAdminApi <https://sdk.innovaphone.com/14r1/doc/appwebsocket/PbxAdminApi.htm>`_
.

Example to get a specific user object from the pbx:

.. code-block::
    
  curl 'https://apps.example.com/example.com/grpapi1/api/pbx' \
      -H 'Authorization: Bearer 98ms098sm09s8ms098sm09s8m' \
      -X 'POST' \
      -d '{
          "mt": "GetObject",
          "api": "PbxAdminApi",
          "cn": "testcaller5"
      }'

The response would contain the user object as JSON formated data.

.. code-block:: JSON

  {
    "api": "PbxAdminApi",
    "src": "callback0.6236058413386716",
    "mt": "GetObjectResult",
    "guid": "fa573952f5f461014152009033400109",
    "cn": "testcaller5",
    "dn": "testcaller5__",
    "h323": "testcaller5",
    "e164": "255",
    "node": "root",
    "loc": "pbx-main",
    "ext-in": false,
    "config": "",
    "local": false,
    "trace": false,
    "hide": false,
    "critical": false,
    "no-dev": false,
    "login-c": 0,
    "login-t": 0,
    "filter": "normal",
    "phone": {},
    "devices": [],
    "grp": [
      {
        "name": "Support"
      }
    ],
    "presence": [],
    "wakeups": [],
    "gws": [],
    "profiles": []
  }


/objects GET
------------

Returns a list of the userobjects replicated from the pbx ordered by GUID.

.. code-block::
    
  curl 'https://apps.example.com/example.com/grpapi1/api/objects' \
      -H 'Authorization: Bearer 98ms098sm09s8ms098sm09s8m' \
      -X 'GET'

.. code-block:: JSON

  {
    "09eaa7a67b204d32afc7ba706c9ccdc8": {
      "guid": "09eaa7a67b204d32afc7ba706c9ccdc8",
      "h323": "patient21",
      "cn": "Patient 21_",
      "dn": "21, Patient",
      "node": "master",
      "loc": "pbx-main",
      "grps": [
        {
          "name": "Patienten"
        }
      ],
      "pseudo": "user"
    },
    "0c368691dba74ca0bbb2af3de80cd261": {
      "guid": "0c368691dba74ca0bbb2af3de80cd261",
      "h323": "patient39",
      "cn": "Patient 39",
      "dn": "39, Patient",
      "node": "master",
      "loc": "pbx-main",
      "grps": [
        {
          "name": "Patienten"
        }
      ],
      "pseudo": "user"
    },
    ...


/set POST
------------

Overwrite a objects groupsettings regarless of its current memberships.

.. code-block::
    
    curl 'https://apps.example.com/example.com/grpapi1/api/set' \
      -H 'Authorization: Bearer 98ms098sm09s8ms098sm09s8m' \
      -X 'POST' \
      -d '{
          "cn": "Patient 39",
          "grp": [
            {
              "name": "Support"
            },
            {
              "name": "TestGroup1",
              "mode": "active",
              "dyn": "in"
            }
          ]
        }'


.. code-block:: JSON

  {
    "api": "PbxAdminApi",
    "src": "callback0.7737017036309024",
    "mt": "GetObjectResult",
    "guid": "0c368691dba74ca0bbb2af3de80cd261",
    "cn": "Patient 39",
    "dn": "39, Patient",
    "h323": "patient39",
    "e164": "442",
    "node": "master",
    "loc": "pbx-main",
    "ext-in": false,
    "config": "Config User",
    "apps-my": "users",
    "local": false,
    "trace": false,
    "hide": false,
    "critical": false,
    "no-dev": true,
    "login-c": 0,
    "login-t": 0,
    "filter": "_International",
    "phone": {},
    "grp": [
      {
        "name": "Support"
      },
      {
        "name": "TestGroup1",
        "mode": "active",
        "dyn": "in"
      }
    ],
    "presence": [],
    "wakeups": [],
    "gws": [],
    "profiles": []
  }