Versionen im Vergleich

Schlüssel

  • Diese Zeile wurde hinzugefügt.
  • Diese Zeile wurde entfernt.
  • Formatierung wurde geändert.

Status
colourYellow
titleWMS 1.1.4

Hier wird erläutert, wie Sie mit dem WMS eine REST-API (oder eine andere HTTP-API) ansprechen und nutzen können. Es wird zunächst kurz auf die Grundlagen und Unterschiede von HTTP-Requests REST und REST Http eingegangen. Anhand von Beispielen wird gezeigt, wie Sie mit dem WMS externe Schnittstellen ansprechen.

Inhalt

Inhalt
API

Was ist eine API?

API steht für “Application Programming Interface” und beschreibt die eine Schnittstelle einer Anwendung oder eines HerstellersDienstes. Über die Schnittstelle können Daten abgerufen, geändert und auch gelöscht werden. Die API wird von dem jeweiligen Hersteller definiert und unterscheidet sich von Anwendung zu Anwendung. Deshalb sollte die API detailliert beschrieben sein, um diese vernünftig nutzen zu können. Es gibt verschiedene Arten von APIs, jedoch wollen wir uns hier auf diejenigen beschränken, welche mit HTTP-Requests über Http angesprochen werden können (z.B. REST-API’sAPI).

Inhalt

Inhalt

HTTP-Request

Ein HTTP-Request (zu deutsch “Anfrage”“Http-Anfrage”) wird von einem Client (in unserem Falle das WMS) an einen benannten Host (die Anwendung auf einem Server, welche die API bereitstellt) gesendet.

Um einen HTTP-Request abzusenden wird als Adresse eine URL (Uniform Resource Locator) verwendet, welche alle Informationen enthalten muss, um die die API exakt zu adressierenerwartet. Wie die Bezeichnung “Uniform Resource Locator” bereits ausdrückt, wird mit der URL eine Resource eine “Quelle” adressiert, von der Daten abgerufen bzw. an die Daten gesendet werden können.

Um mit dem Host zu kommunizieren, müssen dem HTTP-Request noch weitere Informationen mitgegeben werden. Diese Informationen sollten in der API-Beschreibung des Herstellers dokumentiert sein.

HTTP-Endpunkt (URL)

Eine URL besteht normalerweise aus folgenden Komponenten Teilen (erklärt an der API von Microsoft Graph):
Beispiel-URL:

Panel
bgColor#F4F5F7

https://graph.microsoft.com:8080/v1.0/me/joinedTeams?

querySchema

p1=A&p2=B#ressource
\____/ \___________________/ \__/ \______________________/ \____________/ \________/
| | | | | |
Schema Host Port Pfad Query Fragment

Schema: Gibt das verwendete Protokoll an, mit dem der Request gesendet wird.

Dies ist entweder

Hier: httpoder https

.

Host


: Der Host-Name identifiziert den Host, welcher die API bereitstellt.

Der

Statt dem Host-

Name

Namen kann

eine

auch dessen IP-Adresse

und einen Port enthalten.
Im Beispiel entspricht der Hostname graph.microsoft.comPfad

angegeben werden.

Port: Der Port muss angegeben werden, wenn er nicht dem Standard entspricht. (Standard Http-Port: 80, HTTPS: 443)

Pfad: Der Pfad gibt die Resource an, welche adressiert werden soll, im Beispiel /v1.0/me/joinedTeams.
Oftmals gibt es einen Basis-Pfad, welcher bei unterschiedlichen Requests immer gleich bleibt. Im Beispiel wäre dies die Versionsnummer der API /v1.0.
Der Pfad kann auch zu einer Datei führen (einer Html-Datei zur Anzeige im Browser oder eine PDF-Datei zum Herunterladen von Binärdaten)

Query


: Beim Absetzen eines Requests kommt es häufig vor, dass zusätzliche Parameter (z.B. Filter oder IDs) mitgegeben werden müssen. Die Query besteht aus ein oder mehreren Namen/Werte-Paaren, welche mit einem “&” separiert werden, und wird am Ende des Pfades mit einem “?” angehängt (z.B. ?user=Mustermann&zipcode=83022).

Um mit dem Host zu kommunizieren, müssen dem HTTP-Request noch weitere Informationen mitgegeben werden.

Fragment: Mit dem Fragmentbezeichner (eingeleitet mit einem #) kann eine Untereinheit einer Ressource adressiert werden kann.

HTTP Methode

Mit der Methode wird angegeben, was mit den Daten gemacht werden soll. Am gebräuchlichsten ist die Methode GET, mit der Daten von einer API abgerufen werden können. Darüber hinaus gibt es noch die Methoden PATCH, POST, PUT, DELETE und weitere, mit denen Daten geändert bzw. gelöscht werden können.

HTTP Header

Die Header werden als Liste von Namen/Werte-Paaren mitgegeben. Im Header werden Informationen über den Sender und die Kommunikation mitgegeben, z.B. auch die Formatierung der im Content übergebenen Daten. Welche Header benötigt werden, wird sollte in der API beschrieben sein.

Content

Im Content (auch als Body bezeichnet) werden dem HTTP-Request zusätzliche Daten mitgegeben. Dies ist üblicherweise bei Hinzufügen oder Ändern von Daten der Fall (also bei den Methoden PATCH, POST, PUT). Der Content kann Textform (z.B. im Json- oder XML-Format) oder als Name/Wert-Paare (form-urlencodedurl-encoded) übergeben werden. Daten werden dann bevorzugt im Content übermittelt, wenn sie sehr umfangreich sind oder nicht in der URL ersichtlich sein sollen.

HTTP-Response

Wurde ein HTTP-Request abgesetzt, gibt der Host eine Antwort auf den Request zurück, die sog. HTTP-Response. Mit der HTTP-Response werden folgende Informationen zurückgegeben:

Ein Status-Code, ein 3-stelliger numerischer Wert, mit dem die erfolgreiche Ausführung des HTTP-Request bestätigt (Status-Code 200) oder eine nicht ordnungsgemäße Anfrage angezeigt wird. Der Status-Code wird in folgende 5 Gruppen unterteilt:

  • 1xx - Informell
    Die Anfrage wurde empfangen und die serverseitige Verarbeitung wird fortgesetzt

  • 2xx - Erfolgreich
    Die Anfrage wurde erfolgreich empfangen und angenommen

  • 3xx - Nachsendung
    Weitere Aktionen sind erforderlich, um den Request abzuschließen

  • 4xx - Fehler beim Client
    Der HTTP-Request enthält eine ungültige Syntax und kann nicht ausgeführt werden (z.B. fehlende oder ungültige Credentials)

  • 5xx - Fehler beim Host
    Bei der Verarbeitung auf dem Server sind Fehler aufgetreten

Details zu den einzelnen Codes können Sie hier nachlesen: https://de.wikipedia.org/wiki/HTTP-Statuscode.

Der Grunddes Status-Codes, welcher eine textuelle Beschreibung im Falle eines Fehlers beinhaltet.

Eine Liste mit Headern, welche zusätzliche Informationen zum Host und der Kommunikation liefern, darunter auch die Formatierung eines zurückgegebenen Contents.

Im Content (auch als Body bezeichnet) werden im Allgemeinen die angeforderten Daten zurückgegeben.

REST

REST steht für REpresentational State Transfer und stellt eine Architektur für die Kommunikation von verteilten Anwendungen dar. Mit REST werden Prinzipien definiert, welche von einer API umgesetzt sein müssen, wenn diese als REST API bezeichnet wird. Werden alle diese Prinzipien von einer Service-Schnittstelle implementiert, wird diese auch als RESTful bezeichnet.

Im Sprachgebrauch werden häufig Http-APIs als REST-API bezeichnet, auch wenn sie die Kriterien nicht erfüllen.

In der Regel basiert eine REST API auf dem HTTP-Protokoll und kann dann uneingeschränkt mit HTTP-Requests angesprochen werden.

Tools

Wenn eine Web-Service-API genutzt werden soll, ist es hilfreich, wenn man die API bereits im Vorfeld testen und mit den Möglichkeiten der API spielen kann, bevor diese mittels der Aktivität “HTTP-Request senden” angesprochen wird. Speziell für diese Aufgabe gibt es im Internet kostenlose Tools, wie z.B.


Verwandte Themen

HTTP Requests im WMS

Nach Stichwort filtern (Inhalt nach Stichwort)
showLabelsfalse
showSpacefalse
cqllabel = "http" and type = "page" and space = "APM2019DE" and ancestor = "150667523"

Beispiele zum Absenden von HTTP Requests mit dem WMS

Nach Stichwort filtern (Inhalt nach Stichwort)
showLabelsfalse
showSpacefalse
cqllabel = "http" and label in ( "tutorial" , "hilfe" , "beispiel" ) and space = "APM2019DE"