Wir werden erklären, was eine HTTP-Anfrage und eine HTTP-Antwort sind und wie sie aufgebaut sind.

1 – Die HTTP-Anfrage

Eine HTTP-Anfrage ist in einer bestimmten Weise strukturiert, damit der Server sie verstehen kann. Sie besteht aus drei Teilen:

    Die Befehlszeile: Sie enthält die Methode, den Pfad und die Protokollversion.
    Der Request-Header: enthält eine Reihe von optionalen Zeilen, die zusätzliche Informationen über den Server oder den Client enthalten.
    Der Körper der Anfrage: enthält eine Reihe von optionalen Zeilen, die den Daten entsprechen, die über ein Formular gesendet werden.

Eine Methode ist ein Befehl, der die Art der Anfrage angibt, d. h. was der Server tun soll. Zum Beispiel, eine Ressource abrufen oder sie speichern. Es gibt mehrere Methoden, aber wir werden nur die erwähnen, die wir als nächstes verwenden werden:

 – GET : diese Methode wird verwendet, um eine Ressource anzufordern (was eine Ressource ist, wird im nächsten Abschnitt erläutert), sie hat keine Auswirkungen auf die Ressource

– POST : wird verwendet, um Daten zu übermitteln, das Ergebnis kann die Erstellung einer neuen Ressource sein.

– PUT : diese Methode kann verwendet werden, um eine Ressource zu ersetzen oder hinzuzufügen.

– PATCH : diese Methode wird verwendet, wenn Sie eine Ressource teilweise ändern wollen.

– DELETE : diese Methode wird verwendet, um eine Ressource zu löschen.
Die HTTP-Antwort

Die HTTP-Antwort

Eine HTTP-Antwort ist ebenfalls auf eine bestimmte Art und Weise strukturiert, sie besteht ebenfalls aus drei Teilen:

    Die Antwortzeile: Sie enthält die Protokollversion, den Statuscode und die Bedeutung dieses Codes.
    Der Antwort-Header: Er enthält optionale Zeilen mit zusätzlichen Informationen über die Antwort und/oder den Server.
    Der Body der Antwort: Er kann das angeforderte Dokument oder die angeforderte Ressource enthalten.

Der Status der Antwort gibt an, ob die Anfrage erfolgreich war oder nicht. Sie sind in fünf Gruppen unterteilt:

    1xx : zeigt Informationen an
    2xx : zeigt an, dass die Anfrage erfolgreich war
    3xx : zeigt eine Umleitung der Anfrage an
    4xx : zeigt an, dass ein Fehler aufgetreten ist, aber die Ursache beim Kunden liegt
    5xx : zeigt an, dass ein Fehler aufgetreten ist, aber dass die Ursache vom Server stammt

Unter diesen Statuscodes gibt es einen, der sehr bekannt ist: der 404-Code, der anzeigt, dass der Kunde eine nicht vorhandene Ressource angefordert hat.

2. Ressource und Sammlung

    Eine Ressource steht für jede Art von Namen, der zur Darstellung von Daten in einer Anwendung verwendet werden kann. So kann beispielsweise die Ressource „Benutzer“ die Daten eines Benutzers oder die Ressource „Artikel“ die Daten eines Beitrags darstellen.
    Jede Ressource enthält zusätzliche Informationen über die Daten, die sie enthält. Für eine Benutzerressource können Sie beispielsweise als zusätzliche Daten seinen Vornamen, seinen Nachnamen und sein Alter angeben.
    Ressourcen werden in einer Gruppe zusammengefasst, die als Sammlung bezeichnet wird. Dies ist der Plural des Ressourcennamens. Für die Ressource Benutzer gibt es beispielsweise die Sammlung Benutzer, für die Ressource Produkt die Sammlung Produkte.

Nachdem wir nun einige Konzepte behandelt haben, wollen wir uns ansehen, wie man eine REST-API entwickelt.

3. Wie entwirft man eine REST-API?

Zunächst einmal: Was ist eine API? Wir können eine API als eine Schnittstelle definieren, über die alle Dienste einer Software zugänglich sind. Die Besonderheit von REST-APIs besteht darin, dass für die Kommunikation das HTTP-Protokoll und für die Strukturierung und den Austausch von Daten das JSON-Format verwendet wird:

    Wie können die Daten dargestellt werden?
    Wie benennt man die Pfade zu einer Ressource?
    Wie stellen wir die Methoden dar?

Wie stellt man die Daten dar?

Daten sind das Herzstück einer Anwendung, daher muss zunächst ein konsistenter Weg gefunden werden, um sie darzustellen. Zunächst werden wir die Daten in mehrere Elemente aufteilen, die wir als Ressourcen darstellen werden. Jede Ressource hat einen Namen und enthält zusätzliche Informationen über die Daten, die sie enthält.

Zweitens werden die Ressourcen in einer Sammlung zusammengefasst. Wir beziehen uns auf eine Sammlung mit der Form des Ressourcennamens im Plural.

Wie benennt man die Pfade zu einer Ressource?

Um einem Client den Zugriff auf Ressourcen zu ermöglichen, stellt unsere API Methoden zur Verfügung. Jede Methode wird über einen so genannten Pfad aufgerufen. Die Aufgabe besteht hier darin, einen einheitlichen Weg zu finden, diese Pfade zu benennen. Es gibt mehrere gute Möglichkeiten, dies zu tun, aber wir werden den folgenden Weg wählen: /api/<die API-Version>/<der Name der Sammlung>.
Wie stellen wir die Methoden dar?

Sobald die Datendarstellung definiert ist, müssen die Methoden für den Zugriff und die Bearbeitung der Daten festgelegt werden.
Wir werden zunächst die Art unserer Methoden definieren. Jede Methode muss eine Aktion ausführen, wobei die Art einer Aktion durch ein HTTP-Verb definiert wird. So werden wir die Methoden für unsere Schuhsammlung definieren und bereitstellen:

    GET /api/v1/shoes : zum Abrufen der Sammlung
    GET /api/v1/shoes/123 : zum Abrufen des Schuhs mit der ID 123
    POST /api/v1/shoes : um eine Ressource zur Sammlung hinzuzufügen
    PUT /api/v1/shoes/123 : um die Schuhressource mit der ID 123 zu ändern
    DELETE /api/v1/shoes/123 : um die Schuhressource mit der ID 123 zu löschen

Als nächstes müssen wir feststellen, ob sich der Client authentifizieren muss, um eine Methode aufzurufen. Zu diesem Zweck muss der Benutzer seine Informationen im Request-Header angeben.

Und schließlich müssen wir die Fehler bestimmen, die beim Aufruf einer Methode auftreten können. Die Art eines Fehlers muss vom Client durch einen Statuscode in der Kopfzeile und eine Meldung im Körper der Antwort bestimmt werden können.

Beispiel: Wir werden die Sammlung Schuhe verwenden

4. Die Dokumentation

Wenn wir mit dem Entwurf unserer API fertig sind und zur Entwicklung übergehen, ist es wichtig, eine Dokumentation für unsere API zu erstellen. Die wichtigsten Informationen in der Dokumentation sind die folgenden:

    Die API-Version
    Verfügbare Ressourcen: Für jede Ressource müssen die Daten, die sie darstellt, dokumentiert werden.
    Die verfügbaren Methoden: Für jede Methode müssen die Definitionen der Anfrage, der Antwort und der verschiedenen Antwortstatus beschrieben werden.

Für die Dokumentation Ihrer API gibt es Technologien, mit denen sie erstellt werden kann. Die Technologie, die ich in meinen Projekten verwende, ist Swagger. Sie ist sehr verbreitet und kann in viele Frameworks integriert werden.