================
API Beschreibung
================

URL
===

Die Stamm-URL der API wird nach folgendem Schema aufgebaut.

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

Als Beispiel:

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

Autorisierung
=============


Ein Header wird in HTTP-Anfragen verwendet, um Authentifizierungsdaten zu übermitteln. 
In unserem Fall wird zu diesem Zweck ein Bearer-Token verwendet. 
Der Header muss in jeder an die geschützten API-Endpunkte gesendeten Anfrage enthalten sein.
Das Bearer-Token kann über das Einstellungsformular der Admin-App geändert werden.

Endpunkte
=========

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

Gibt eine Liste der aktuellen Gruppen und ihrer Mitglieder zurück.

.. 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
------------

Hinzufügen, Ändern oder Löschen von Gruppenmitgliedschaften von Pbxobjects mit einer HTTP ``POST`` Anfrage.
Die POST Anfrage muss eine gültige ``JSON`` formatierte Nachricht enthalten.
Die Schlüssel, die in jeder Anfrage vorhanden sein müssen, sind die folgenden:

+-----------+---------------------------------------------+
| Schlüssel | Wert                                        |
+-----------+---------------------------------------------+
| cn        | der CN des zu ändernden pbx-Objekts         |
+-----------+---------------------------------------------+
| grp       | der Namen der zu ändernden Gruppe           |
+-----------+---------------------------------------------+
| action    | 0=löschen, 1=hinzufügen oder ändern         |
+-----------+---------------------------------------------+
| state     | (optional) 0=static*, 1=dyn-in, 2=dyn-out   |
+-----------+---------------------------------------------+
| active    | (optional) 0=nicht aktiv*, 1=activ          |
+-----------+---------------------------------------------+

Als Beispiel ein Curl-Request zum Hinzufügen des Users ``testcaller5`` zur neuen Gruppe ``TestGroup1`` als ``dyn-in`` als ``aktiv``.

.. 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
    }'

Um einen Benutzer aus einer Gruppe zu entfernen, würde die Nachricht den Inhalt ``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
---------

Bietet generischen Zugriff auf die PbxAdminApi, wie in der `innovaphone SDK docs/ PbxAdminApi <https://sdk.innovaphone.com/14r1/doc/appwebsocket/PbxAdminApi.htm>`_ dokumentiert.
.

Beispiel für das Abrufen eines bestimmten Benutzerobjekts von der Vermittlungsstelle:

.. 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"
      }'

Die Antwort würde das Benutzerobjekt als JSON-formatierte Daten enthalten.

.. 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
------------

Gibt eine Liste der aus der pbx replizierten Benutzerobjekte zurück, geordnet nach 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
------------

Überschreibt die Gruppeneinstellungen eines Objekts, unabhängig von seinen aktuellen Mitgliedschaften.

.. 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": []
  }