Zum Inhalt

Einleitung

Hier finden Sie eine Beschreibung der VoIPstudio API, die den Zugang zu allen Ressourcen der Plattform ermöglicht.

Allgemein

Die REST-API ermöglicht VoIPstudio-Kunden den Zugriff auf eine breite Palette von Ressourcen. Unsere API hat vorhersehbare, ressourcenorientierte URLs und verwendet HTTP-Antwortcodes, um API-Fehler anzuzeigen. Wir verwenden integrierte HTTP-Funktionen wie HTTP-Verben, die von handelsüblichen HTTP-Clients verstanden werden. Wir unterstützen die herkunftsübergreifende gemeinsame Nutzung von Ressourcen, so dass Sie von einer clientseitigen Webanwendung aus sicher mit unserer API interagieren können. JSON wird von allen API-Antworten zurückgegeben, auch bei Fehlern.

Endpunkte

Die Basis-URL für die API lautet:

https://l7api.com/v1.2/voipstudio/

Authentifizierung

Bevor Sie Anfragen an die API von VoIPstudio senden, müssen Sie zunächst einen API-Schlüssel, auch bekannt als "user_token", erstellen, der zur Autorisierung aller Anfragen verwendet wird.

Sie können den API-Schlüssel / user_token auf eine der beiden folgenden Arten erzeugen:

  1. Senden Sie eine POST-Anfrage an den Endpunkt "/login" mit E-Mail und Passwort als Anmeldeinformationen.
  2. Verwenden Sie VoIPstudio Web Dashboard, um API Key / user_token zu erstellen.

Detaillierte Anweisungen finden Sie unten:

Anmeldung mit E-Mail und Kennwort

Login-Anfrage mit E-Mail und Passwort:

curl -X POST -H "Content-Type: application/json" \
     https://l7api.com/v1.2/voipstudio/login \
     -d '{"email":"jsmith@example.com","password":"$ecretPas$$"}'

Beispielanfrage:

POST /v1.2/voipstudio/login HTTP/1.1
Host: l7api.com
Content-Type: application/json
{"email":"jsmith@example.com","password":"$ecretPas$$"}

Beispiel für eine erfolgreiche Antwort:

{
    "message":"Login success",
    "user_token":"123456abc993ba5dd8a0e7ce9876543",
    "user_id":123456
}

Standardmäßig läuft user_token nach 30 Minuten Inaktivität ab (d.h. es werden keine API-Anfragen gestellt). Jedes Mal, wenn eine API-Anfrage gestellt wird, wird der Verfallstimer zurückgesetzt.

Wenn Sie API-Tokens mit längerer Ablaufzeit benötigen, können Sie nach dem Erhalt des anfänglichen user_token mit POST /login zusätzliche API-Schlüssel erstellen, indem Sie POST /apitokens senden:

curl -X POST -H "Content-Type: application/json" \
     -H "X-Auth-Token: 123456abc993ba5dd8a0e7ce9876543" \
     https://l7api.com/v1.2/voipstudio/apitokens \
     -d '{"name":"Example API App","expiry":604800}'

Beispiel für eine erfolgreiche Antwort:

{
    "data":{
        "user_id":123456,
        "token":"9843211cb48787655cddb080ebdabced",
        "customer_id":521156,
        "name":"Example API App",
        "host":"8.8.8.8",
        "user_agent":"curl/7.58.0",
        "expiry":604800,
        "last_request_at":null,
        "created_at":"2023-02-09 17:20:01"
    },
    "links":{}
}

Hinweis: Um einen API-Schlüssel zu erstellen, der nie abläuft, verwenden Sie "expiry":0" in der Nutzlast der POST-Anfrage /apitokens.

Web Dashboard - API-Schlüssel hinzufügen

Führen Sie die folgenden Schritte aus, um einen API-Schlüssel für einen Benutzer hinzuzufügen:

  1. Bearbeiten Sie im Verwaltungsbereich den Benutzer, für den API-Schlüssel hinzugefügt werden müssen.
  2. Gehen Sie zum Abschnitt API-Schlüssel.
  3. Geben Sie einen Namen für Ihren API-Schlüssel ein, den Sie frei wählen können. Zum Beispiel den Namen Ihrer Anwendung, die diesen API-Schlüssel verwenden wird.
  4. Klicken Sie auf die Schaltfläche "Hinzufügen".
  5. Klicken Sie auf das Symbol "Auge", um den aktuellen API-Schlüssel / user_token abzurufen.
  6. Klicken Sie auf das "Zahnrad"-Symbol und wählen Sie "Details anzeigen", um weitere Details zu erhalten oder den API-Schlüssel zu löschen.

api-key-add.png

Figure 1.1 Add API Key.

Anfragen stellen

Eingehende Anfragen, die von unserer API bearbeitet werden, müssen einen X-Auth-Token-Header mit dem Wert user_token (API-Schlüssel) enthalten, der von einer erfolgreichen POST /login oder POST /apitokens Antwort zurückgegeben wird. 

X-Auth-Token: TOKEN

Beispiel einer authentifizierten Anfrage:

curl -H "Content-Type: application/json"
     -H "X-Auth-Token: 123abc45678def3234sdfgdf3434df3444" \
     https://l7api.com/v1.2/voipstudio/cdrs

HTTP-Antworten

VoIPstudio REST API verwendet herkömmliche HTTP-Antwortcodes, um den Erfolg oder Misserfolg einer API-Anforderung anzuzeigen. Im Allgemeinen weisen Codes im 2xx-Bereich auf einen Erfolg hin, Codes im 4xx-Bereich auf einen Fehler, der angesichts der bereitgestellten Informationen fehlgeschlagen ist (z. B. wurde ein erforderlicher Parameter ausgelassen usw.), und Codes im 5xx-Bereich auf einen Serverfehler.

Jede erfolgreiche Antwort enthält, je nach HTTP-Methode, die folgenden Eigenschaften

  • GET Sammlung von Ressourcen:

    • data - eine Reihe von Ressourcendaten
    • total - Gesamtzahl der Ressourcen

  • GET einzelne Ressource:

    • data - Ressourcen-Daten
    • links - Links zu ähnlichen Ressourcen

Jede Fehlerantwort enthält die folgenden Eigenschaften:

  • message - allgemeine Fehlermeldung
  • errors - eine Reihe von Fehlermeldungen

Pager

Bei Datenerfassungsendpunkten wie GET https://l7api.com/v1.2/voipstudio/cdrs kann ein Pager verwendet werden, um eine bestimmte Anzahl von Datensätzen von einer bestimmten Seite im Datensatz zurückzugeben. Um Pager anzuwenden, fügen Sie bitte die folgenden Parameter an die URL an: ?page=N&limit=Z, wobei N eine Seitennummer und Z die Anzahl der zurückzugebenden Datensätze ist (maximal 5000).

Filters

Um Daten zu filtern, kann der Parameter filter als URL-Abfragezeichenfolge übergeben werden. Der Wert des Parameters filter muss eine JSON-kodierte Zeichenkette in dem unten dargestellten Format sein:

[
   {"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"},
   {"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"}
   ...
]

Die drei obigen Token _PROPERTY_NAME_, _OPERATOR_ und _VALUE_TO_SEARCH_ sind wie folgt zu interpretieren:

  • _PROPERTY_NAME_ dies kann jede Eigenschaft sein, die zu einem bestimmten Endpunktobjekt gehört. Eine ausführliche Erläuterung des Datenmodells für jeden Endpunkt finden Sie im Abschnitt "Ressourcen" weiter unten.

  • _OPERATOR_ kann eine der folgenden sein:

    • eq oder =, wenn nach Datensätzen gesucht wird, deren "property"-Wert gleich ist mit _SEARCH_VALUE_
    • ne, neq, <> oder !=, wenn nach Datensätzen gesucht wird, deren "property"-Wert NICHT gleich ist mit _SEARCH_VALUE_
    • lt oder < bei der Suche nach Datensätzen mit einem "property"-Wert kleiner als _SEARCH_VALUE_
    • lte oder <=, wenn nach Datensätzen gesucht wird, deren "property"-Wert kleiner als oder gleich _SEARCH_VALUE_ ist
    • gt oder >, wenn nach Datensätzen gesucht wird, deren "property"-Wert größer als _SEARCH_VALUE_ ist
    • "gte" oder ">=" bei der Suche nach Datensätzen mit dem Wert "Eigenschaft" größer oder gleich "SUCHE_WERT_
    • in bei der Suche nach Datensätzen, deren "property"-Wert in _SEARCH_VALUE_ enthalten ist (Hinweis: Der Suchwert muss als Array übergeben werden, z.B.: [ "foo", "bar" ])
    • like bei der Suche nach Datensätzen mit "property"-Wert matching pattern von _SEARCH_VALUE_
    • notlike, wenn nach Datensätzen gesucht wird, deren "property"-Wert NICHT dem Muster von _SEARCH_VALUE_ entspricht

  • _SEARCH_VALUE_ den Wert, nach dem Sie suchen möchten

Beispiel für eine Anfrage an den Endpunkt /cdrs zur Suche nach eingehenden Anrufen (Eigenschaft dst_id entspricht der Benutzer-ID) an die Benutzer-ID 123456 nach dem 1. September 2018:

curl -H "X-Auth-Tokeb: TOKEN" -H "Content-Type: application/json"
     'https://l7api.com/v1.2/voipstudio/cdrs?filter=[
       {"property":"dst_id","operator":"eq","value":"123456"},
       {"property":"calldate","operator":"gt","value":"2018-09-01 00:00:00"}
     ]'

Gruppieren

Der Parameter group_by ist für die Gruppierung von Datensätzen nach bestimmten Eigenschaften verfügbar: GET https://l7api.com/v1.2/voipstudio/cdrs?group_by=src. Dieser Parameter sollte als URL-Abfrage-String übergeben werden.