close

Anmelden

Neues Passwort anfordern?

Anmeldung mit OpenID

Rest Webservices - outbox AG

EinbettenHerunterladen
Allgemeine Dokumentation der
RESTful Webservices
outbox AG . Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
ALLGEMEINE ERKLÄRUNGEN ...................................................................................................................... 3
 EINFÜHRUNG ................................................................................................................................................ 3
 ANSTEUERUNG DER W EBSERVICES ............................................................................................................ 3
 URL DER W EBSERVICES ............................................................................................................................. 3
 HTTP-METHODEN ....................................................................................................................................... 4
 AUTHENTIFIZIERUNG .................................................................................................................................... 4
 PARAMETERÜBERGABE................................................................................................................................ 4
API-EXPLORER ................................................................................................................................................... 6
 ÜBERSICHT................................................................................................................................................... 6
 ANZEIGE DER FUNKTIONSREFERENZ........................................................................................................... 7
 AUFRUF EINER FUNKTION ............................................................................................................................ 8
DATENFORMATE ............................................................................................................................................... 9
2
outbox AG . Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
Allgemeine Erklärungen
Einführung
Diese Dokumentation richtet sich primär an Entwickler, die basierend auf den
Webservices des gebuchten Produktes eine eigene Applikation entwickeln möchten. Es
wird vorausgesetzt, dass der Leser ein grundlegendes Verständnis der folgenden
Technologien hat:





HTTP-Protokoll
RESTful Webservices
JSON
XML
YAML
Ansteuerung der Webservices
Unsere RESTful Webservices ermöglichen Ihnen den Zugriff auf Ressourcen über URIPfade. Um Ihre RESTful Webservices zu verwenden, sendet die Anwendung HTTPAnfragen und parst bzw. analysiert die Antwort.
Unsere RESTful Webservices verwenden JSON als Standard-Kommunikations-Format,
Sie können allerdings auch mit Hilfe von XML oder YAML verwendet werden. Es werden
die HTTP-Methoden GET, PUT, POST und DELETE eingesetzt.
Der Zugriff ist ausschließlich über das HTTPS-Protokoll möglich.
URL der Webservices
Die URL der Webservices Ihres gebuchten Produktes erhalten Sie zusammen mit Ihrer
Auftragsbestätigung.
Hinweis: Jede Version ist unter einer eigenständigen URL ansprechbar. Somit ist
gewährleistet, dass Ihrerseits ein kontrollierter Wechsel bei Einführung einer neuen
Version möglich ist.


3
.
outbox AG Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
HTTP-Methoden
Nachfolgend werden die genutzten HTTP-Methoden kurz erläutert:
Methode
Beschreibung
GET
Dient der Abfrage von Informationen
POST
Wird zum Anlegen einer Ressource verwendet
PUT
Wird verwendet, um eine Ressource zu aktualisieren.
DELETE
Löscht eine Ressource
Authentifizierung
Die Authentifizierung erfolgt zum einen durch Übermittlung eines API-Keys, den Sie
zusammen mit Ihrer Auftragsbestätigung erhalten. Diesen können Sie über das
Webfrontend des gebuchten Produktes jederzeit ändern.
Des Weiteren erfolgt die Authentifizierung für den Zugriff auf Ihre API über Ihre IPAdresse(n). Wir empfehlen, nur IP-Adressen freizugeben, die Sie auch wirklich nutzen.
Jede zusätzliche IP-Adresse, stellt grundsätzlich ein unnötiges Sicherheitsrisiko dar.
Parameterübergabe
Sofern nicht anders angegeben, können alle Parameter entweder im Query String oder
im gewünschten Datenformat im Request Body übergeben werden. Wir empfehlen
ausdrücklich die Übertragung der Parameter im Request Body.
Nachfolgend stellen wir Ihnen ein (einfaches) Code-Beispiel (mit PHP und der Zend2
Komponente „Zend\Http\Client“ umgesetzt), das die Übermittlung von
Parameterwerten im Body verdeutlicht.
In unserem Beispiel wird der Befehl put /v4/customer/{customerId} auf den
Customer mit der ID 12 angewendet. Die Customer-ID 12 ist im Pfad der URL
angegeben, der Api-Key als Query-String.
Über die (Instanz)-Funktion „setRawBody“ werden die Parameter
„customernumberAdditional“ und „comment“ (in JSON-Notation) mit den Werten
„12345“ bzw. „Dies ist ein Beispiel-Kommentar“ im Body gesetzt.
4
.
outbox AG Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
$baseUrl = 'Ihre Basis URL zum API';
$client = new Zend\Http\Client($baseApiExplorerUrl.' /v4/customer/12?api_key=
Ihr-API-Key');
$client->setMethod('PUT');
$client->setRawBody(
'{
"customernumberAdditional": "12345",
"comment": "Dies ist ein Beispiel-Kommentar"
}');
$client->setEncType('application/json');
$result = $client->send();
echo $result->getBody();
5
.
outbox AG Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
API-Explorer
Zu unseren REST-Webservices bieten wir eine Weboberfläche an, der Sie die
zugehörigen Anforderungs- und Antwortstrukturen entnehmen können. Der API-Explorer
dient des Weiteren als Befehlsreferenz der Webservices.
Nachfolgend möchten wir Sie mit den grundlegenden Funktionen des API-Explorers am
Beispiel des Produktes click2 vertraut machen.
Bitte beachten Sie, dass über den API-Explorer nur die Rückgabe von JSON erfolgt!
Übersicht
Bei Aufruf des API-Explorers wird zunächst eine Übersicht der verfügbaren
Funktionen/Methoden angezeigt. Im Header haben Sie die Möglichkeit, Ihren API-Key zu
hinterlegen um die Funktionen auch direkt über den API-Explorer aufzurufen.


6
.
outbox AG Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
Anzeige der Funktionsreferenz
Mit einem Klick auf „Expand Operations“ wird die Referenz der ausgewählten Funktion
angezeigt.
Die Gliederung der Referenz erfolgt wie oben angezeigt und enthält folgende Angaben.
Bereich
Beschreibung
HTTP-Methode
Im Kopfbereich finden Sie die Angabe, um welche HTTP-Methode es
sich bei der Funktion handelt. Das oben genannte Beispiel wird mit
einem GET-Request angesprochen.
Kurzbeschreibung
Im Kopfbereich ist ebenfalls eine Kurzbeschreibung der Funktion
gelistet. Die Beispielfunktion dient dem Abruf von CDR-Daten
Implementation Notes
Beschreibt die Funktion der ausgewählten Methode.
Rückgaben
Beschreibt die Parameter,
zurückgegeben werden.
die
bei
Aufruf
der
Funktion
7
.
outbox AG Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
Bereich
Beschreibung
Parameters
Hier werden die verfügbaren Übergabeparameter aufgelistet
Für jeden
verfügbar:
Übergabeparameter sind folgende Informationen

Name des Parameters

Datentyp des Parameters

Beschreibung des Parameters
Im Value-Feld können Sie entsprechende Daten hinterlegen, mit
denen Sie einen Aufruf starten können. Dies erfolgt über den Button
„Try it out“.
Aufruf einer Funktion
Sofern Sie eine Funktion über den Button „Try it out“ aufgerufen haben, wird der Bereich
der Funktionsreferenz um die Daten des API-Aufrufs erweitert:
8
.
outbox AG Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
Die Gliederung erfolgt wie oben dargestellt und enthält folgende Angaben.
Bereich
Beschreibung
Request URL
Zeigt die URL an, die für den Aufruf genutzt wurde.
Response Body
Enthält die Rückgabe des Aufrufs
Response Code
Enthält den HTTP-Status Code
Response Headers
Header des Response


Datenformate
Unsere RESTful-Webservices kann wahlweise die Formate JSON, YAML und XML
zurückgeben. Welches Dateiformat zurückgegeben wird, ermittelt unser System
automatisch auf Basis des von Ihnen genutzten Systems.
Um zu vermeiden, dass Ihr System nicht kompatible Datenformate von unserem System
erhält, empfehlen wir ausdrücklich, den gewünschten Dateitypen beim Aufruf des
Befehls zu übermitteln.
Datenformat
Beispielaufruf
JSON
https://API-URL/cdr.json
XML
https://API-URL/cdr.xml
YAML
https://API-URL/cdr.yaml
9
.
outbox AG Emil-Hoffmann-Straße 1a . 50996 Köln . Tel: +49 22 36 / 30 30
www.outbox.de · support@outbox.de
Document
Kategorie
Internet
Seitenansichten
39
Dateigröße
253 KB
Tags
1/--Seiten
melden