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.2/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.2/voipstudio/login
Beispielanfrage:
POST /v1.2/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.2/voipstudio/cdrs
or
curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:API_Key')" https://l7api.com/v1.2/voipstudio/cdrs
oder einfach:
curl -u user_id:user_token -H "Content-Type: application/json" https://l7api.com/v1.2/voipstudio/cdrs
or
curl -u user_id:API_Key -H "Content-Type: application/json" https://l7api.com/v1.2/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 Ressourcendatentotal
- Gesamtzahl der Ressourcen
-
Einzelne Ressource abrufen:
data
- Ressourcendatenlinks
- Links zu verwandten Ressourcen
Jede Fehlerantwort enthält die folgenden Eigenschaften:
* `message` - allgemeine Fehlermeldung
* `errors` - eine Reihe von Fehlermeldungen
Pager und Filter¶
Für Datenerfassungsendpunkte wie GET https://l7api.com/v1.2/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.2/voipstudio/cdrs?group_by=src
. Dieser Parameter sollte als URL-Abfragezeichenfolge übergeben werden.