Einleitung¶

Allgemein¶

Mit der REST-API können VoIPstudio -Kunden auf eine Vielzahl von Ressourcen zugreifen. Unsere API verfügt über vorhersehbare, ressourcenorientierte URLs und verwendet HTTP-Antwortcodes, um API-Fehler anzuzeigen. Wir verwenden integrierte HTTP-Funktionen wie HTTP-Authentifizierung und HTTP-Verben, die von handelsüblichen HTTP-Clients verwendet werden. Wir unterstützen die gemeinsame Nutzung ursprungsübergreifender Ressourcen, sodass Sie von einer clientseitigen Webanwendung aus sicher mit unserer API interagieren können. JSON wird von allen API-Antworten einschließlich Fehlern zurückgegeben.

Endpunkte¶

The base URL for the API id:

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

Authentifizierung¶

Die Kommunikation zwischen Kundenanwendungen und der API von VoIPstudio wird über SSL durch HTTP basic authentication gesichert.

Bevor Sie Anfragen an die API senden, müssen Sie sich zuerst mit Ihrer E-Mail-Adresse und Ihrem Passwort anmelden oder einen API-Schlüssel erstellen, der für die Autorisierung verwendet wird. Nach erfolgreicher Authentifizierung gibt die API eine eindeutige Benutzer-ID und ein eindeutiges Benutzer-Token zurück, die zur Anmeldung verwendet werden sollen.

E-mail und Passwort¶

Login request using e-mail and password:

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

Beispielanfrage:

POST /v1.1/voipstudio/login HTTP/1.1
User-Agent: curl/7.26.0
Host: l7api.com
Accept: */*
Content-Type: application/json
Content-Length: 55
Connection: close
{"email":"jsmith@example.com","password":"$ecretPas$$"}

Beispiel für eine erfolgreiche Antwort:

  {
"message":"Login success",
"user_token":"8e9bc12575e639c993ba5dd8a0e7ce2250211b9a",
"user_id":123456
}

REST API Schlüssel¶

Um einen Benutzer mit einem API-Schlüssel zu authentifizieren, ist keine Anmeldung erforderlich. Der API-Schlüssel muss für diesen Benutzer in der Registerkarte Erweitert des Benutzers hinzugefügt werden (see: https://voipstudio.de/app/#manual.administrator.users.edit).

Dieser API Key sollte während des Anmeldevorgangs anstelle des user_token verwendet werden.

Kommunikation¶

Die Authentifizierung an der API erfolgt über HTTP Basic Auth. Diese Art der Authentifizierung sollte in der von Ihnen verwendeten Sprache problemlos möglich sein. Eingehende Anfragen, die von unserer API bearbeitet werden, müssen einen speziellen Header mit einem base64-codierten Wert haben, der aus user_id und user_token erstellt wurde, die von einer erfolgreichen login -Reaktion oder user_id zurückgegeben wurden und einen API-Schlüssel erstellt haben. Um diesen base64 -Wert zu erhalten, codieren Sie Ihre user_id und user_token, die durch ein Semikolon getrennt sind.

Authorization Header wird im folgenden Format erwartet:

Authorization: Basic base64('user_id:user_token')

or

Authorization: Basic base64('user_id:API_Key')

Beispiel für eine authentifizierte Anfrage:

curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:user_token')"  https://l7api.com/v1.1/voipstudio/cdrs

or

curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:API_Key')"  https://l7api.com/v1.1/voipstudio/cdrs

oder einfach:

curl -u user_id:user_token -H "Content-Type: application/json" https://l7api.com/v1.1/voipstudio/cdrs

or

curl -u user_id:API_Key -H "Content-Type: application/json" https://l7api.com/v1.1/voipstudio/cdrs

HTTP-Antworten¶

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

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

Sammlung von Ressourcen abrufen:
- data - ein Array von Ressourcendaten
- total - Gesamtzahl der Ressourcen
Einzelne Ressource abrufen:
- data - Ressourcendaten
- links - Links zu verwandten Ressourcen

Jede Fehlerantwort enthält die folgenden Eigenschaften:

* `message` - allgemeine Fehlermeldung
* `errors` - eine Reihe von Fehlermeldungen

Für Datenerfassungsendpunkte wie GET https://l7api.com/v1.1/voipstudio/cdrs kann der Pager verwendet werden, um eine bestimmte Anzahl von Datensätzen von einer bestimmten Seite im Datensatz zurückzugeben. Um Pager anzuwenden, hängen Sie bitte die folgenden Parameter an die URL ?page=N&limit=Z where N is a page number and Z die Anzahl der zurückzugebenden Datensätze ist (maximal 5000).

Um Daten zu filtern, kann der Parameter filter als URL-Abfragezeichenfolge übergeben werden. Der Wert des Parameters filter muss eine JSON-codierte Zeichenfolge im folgenden Format sein:

[
{"operator":"like","value":"United States","property":"name"},
{"operator":"eq","value":10,"property":"price"}
]

Datensätze gruppieren¶

Der Parameter group_by ist verfügbar, um Datensätze nach bestimmten Eigenschaften zu gruppieren: GET https://l7api.com/v1.1/voipstudio/cdrs?group_by=src. Dieser Parameter sollte als URL-Abfragezeichenfolge übergeben werden.