REST-APIs verstehen – Ein Leitfaden für Ungeduldige

Crosspost meines Artikels hier

REST (Representational State Transfer) APIs sind das Rückgrat der modernen Webentwicklung. In diesem Artikel erfahren Sie, wie Sie moderne REST-APIs erstellen und verwenden, welche Entwurfsentscheidungen dabei zu berücksichtigen sind und welche Theorie die Grundlage von REST bildet.

Praktischer Leitfaden

Dieser Abschnitt befasst sich mit der Verwendung von REST-APIs mit HTTP und deckt Endpunkte, Methoden, Anforderungen und Antworten ab. Sie finden alles, was Sie brauchen, um API-Aufrufe durchzuführen und REST in Ihren Projekten anzuwenden.

So strukturieren Sie Ihre URIs

Im Allgemeinen gibt es zwei Möglichkeiten, einen URI zu behandeln:

1. Als Aktion
2. Als Ressource

Berücksichtigen Sie die beiden folgenden URIs:

1. https://example.com/getUserData?id=1 (Aktion)
2. https://example.com/users/1 (Ressource)

Beide Beispiele zeigen uns das Abrufen von Benutzerdaten eines Benutzers mit der ID 1. Der Unterschied besteht darin, dass im ersten Beispiel die Route /getUserData eine Aktion ausführt, während im zweiten Beispiel die Route /users/1 der Standort von ist Wenn es sich um ein Asset handelt, gibt es nicht an, welche Aktion ausgeführt wird. Wir könnten sagen, dass diese Art von URI als Substantiv fungiert (da es sich um eine Sache und nicht um eine Aktion, also ein Verb) handelt.

Das REST-Muster schreibt vor, dass wir ausschließlich URIs wie im zweiten Beispiel verwenden. Wir möchten, dass unsere URIs Substantive sind, damit wir HTTP-Methoden als Verben verwenden können, um Aktionen für diese Substantive auszuführen. Beispielsweise können wir die HTTP-Methode GET verwenden, um Informationen über /users/1 abzurufen, aber wir könnten PUT verwenden, um die Informationen des entsprechenden Benutzers zu aktualisieren, oder DELETE, um den Benutzer vollständig zu löschen.

Das Letzte, was Sie bei URIs beachten sollten, ist, dass, wie im obigen Beispiel, beim Verweisen auf eine einzelne Ressource (z. B. in diesem Fall ein einzelner Benutzer) der URI mit der eindeutigen Kennung für diese Ressource enden sollte. Beim Verweisen auf alle Ressourcen in einer bestimmten Kategorie sollte die eindeutige Kennung weggelassen werden.

1. https://example.com/users/1 – Verweist auf einen bestimmten Benutzer mit der ID 1
2. https://example.com/users – Verweist auf alle Benutzer, unabhängig von der ID

Welche Maßnahmen zu unterstützen sind

Es gibt 4 Hauptaktionen, die in REST unterstützt werden müssen. Wir verwenden das Akronym CRUD, um sie zu merken: Create, Read, U pdate, Delete. Jede dieser Aktionen ist einer HTTP-Methode zugeordnet, die wir zum Ausführen dieser Aktion verwenden können. Die Zuordnung ist wie folgt:

Action	HTTP Method
Create	POST
Read	GET
Update	PUT / PATCH
Delete	DELETE

Alle zu unterstützenden Aktions-URI-Kombinationen

Jede REST-API umfasst eigentlich nur (mindestens) 5-6 Routen. In unserem Beispiel ist der Basisendpunkt /users und wir geben vor, ihn auf https://example.com zu hosten.

• ERHALTEN Sie https://example.com/users
  • Aktion: Alle Benutzer-Assets zurückgeben (jedes Asset ist ein Benutzer)
  • Anfragetext: Leer
  • Antworttext: Liste der Benutzerressourcen (als JSON-Array)
• GET https://example.com/users/[id] ([id] ist eine Variable)
  • Aktion: Gibt nur das einzelne angeforderte Benutzer-Asset zurück
  • Anfragetext: Leer
  • Antworttext: Nur das Benutzer-Asset mit der passenden ID (als JSON)
• POST https://example.com/users
  • Aktion: Fügt der Sammlung ein Benutzer-Asset hinzu
  • Anfragetext: Alle Daten, die zum Erstellen des neuen Benutzer-Assets benötigt werden (kein spezifisches Format erforderlich, JSON empfohlen)
  • Antworttext: Das neu erstellte Asset, dem eine eindeutige ID (als JSON) eingefügt wurde
• PUT https://example.com/users/[id] ([id] ist eine Variable)
  • Aktion: Ersetzt nur die Daten eines vorhandenen Benutzers vollständig durch die angegebenen Daten
  • Anfragetext: Alle Daten, die zum Ersetzen der Daten eines vorhandenen Benutzers erforderlich sind, unabhängig davon, ob sie sich geändert haben oder nicht (abzüglich der ID – kein spezifisches Format erforderlich, JSON empfohlen)
  • Antworttext: Das neu aktualisierte Asset mit der passenden ID (als JSON)
• (Optional) PATCH https://example.com/users/[id] ([id] ist eine Variable)
  • Aktion: Ersetzt teilweise nur die Daten eines vorhandenen Benutzers durch die angegebenen Daten
  • Anfragetext: Nur die Daten, die aktualisiert werden müssen (abzüglich der ID – kein spezifisches Format erforderlich, JSON empfohlen)
  • Antworttext: Das neu aktualisierte Asset mit der passenden ID (als JSON)
• DELETE https://example.com/users/[id] ([id] ist eine Variable)
  • Aktion: Löscht nur einen Datensatz aus der Benutzertabelle
  • Anforderungstext: Keine
  • Antworttext: Keine (nur HTTP-Antwortcode) ODER Die Daten des gerade gelöschten Assets mit passender ID (als JSON)

Designüberlegungen

Abgesehen davon, was einen Endpunkt definiert, ob er das REST-Muster verwendet oder nicht, gibt es viele Dinge zu berücksichtigen, bevor Sie mit der Erstellung eines Endpunkts beginnen. Besteht die Möglichkeit, dass Sie Ihren Endpunkt in Zukunft aktualisieren möchten? Soll Ihre Ausgabe den Benutzern hilfreiche Hinweise geben? Ist REST überhaupt das richtige Muster für Ihre Situation? Lassen Sie uns einige dieser Fragen beantworten.

Versionierung Ihres Endpunkts

Es könnte eine gute Idee sein, gleich zu Beginn über die Versionierung Ihrer API nachzudenken, damit Änderungen in Zukunft einfacher vorgenommen werden können. Es gibt verschiedene Methoden, um zu bestimmen, welche API-Version Ihre Benutzer verwenden möchten:

• URI-Versionierung
  • Die Versionsnummern werden in einen URL-Pfad integriert, normalerweise an der Basis
  • Beispiele:
  • https://example.com/v1/users/1
  • https://example.com/v2/users/1
• Abfrageparameter
  • Die Versionsnummer wird als Abfrageparameter im API-Endpunkt angehängt
  • Beispiele:
  • https://example.com/users/1?apiVersion=1
  • https://example.com/users/1?apiVersion=2
• Headerbasiert
  • Die Versionsnummer ist ein spezifisches und eindeutiges Header-Feld
  • Beispiele (Anforderungsheader):
  • x-api-version: 1
  • x-api-version: 2
• Inhaltsverhandlung
  • Die Version wird basierend auf dem Darstellungszustand oder dem Medientyp bestimmt.
  • Im folgenden Beispiel würde der Servercode wissen, dass „firstName“ für die erste Version gilt und dass er in der nächsten Version in „giveName“ geändert wurde.
  • Beispiele (Anfragetext):
  • { Vorname: 'Henry' }
  • { gegebener Name: 'Henry' }

Verspottung einer Quick-REST-API

Manchmal ist es am besten, mit ihnen herumzuspielen, um zu lernen, wie sie funktionieren. Eine meiner Lieblingsbibliotheken zum Demon von REST ist json-server. Die Einrichtung ist ziemlich einfach – es sind nur ein paar Schritte erforderlich.

JSON-Server installieren

npm install json-server

Erstellen Sie einen einfachen Datenspeicher

{
  "users": [
    { "id": "1", "username": "gorwell", "email": "gorwell@gmail.com" },
    { "id": "2", "username": "cdickens", "email": "cdickens@gmail.com" },
    { "id": "3", "username": "jausten", "email": "jausten@gmail.com" },
    { "id": "4", "username": "vwoolf", "email": "vwoolf@gmail.com" },
    { "id": "5", "username": "sking", "email": "sking@gmail.com" }
  ]
}

Starten Sie den Server

npx json-server db.json

Stellen Sie eine HTTP-Anfrage an Ihren lokalen Server

curl -X GET http://localhost:3000/users/1

Ein einfaches CRUD-Datenraster

Ein voll funktionsfähiger REST-Endpunkt kann mit ZingGrid problemlos an ein Datengrid angeschlossen werden. Richten Sie einfach den Basis-REST-URI auf das src-Attribut des Elements wie unten

<zing-grid
  src="http://localhost:3000/users"
  editor-controls
></zing-grid>

Letzte Gedanken

REST-APIs gibt es im Web in vielen Formen und Größen, jede davon ist auf spezifische Anforderungen zugeschnitten. Indem Sie URIs sorgfältig strukturieren, die richtigen Aktionen auswählen und die Versionierung im Hinterkopf behalten, können Sie eine unkomplizierte, flexible API erstellen, mit der Entwickler gerne arbeiten werden. Mit diesen grundlegenden Schritten kann sich selbst ein schneller Prototyp zu einer robusten, zuverlässigen API entwickeln, die den Test der Zeit besteht.

Das obige ist der detaillierte Inhalt vonREST-APIs verstehen – Ein Leitfaden für Ungeduldige. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!