Verstehen und Verwenden von RESTful APIs

Im Zeitalter des Internet of Everything gibt es viele verschiedene APIs, und es ist wichtig, sie zu standardisieren. Die RESTful API ist einer der beliebtesten API-Architekturstile, der Ihnen helfen kann, Client- und Server-Anliegen zu trennen, sodass Frontend und Backend separat iterieren können, was die Effizienz verbessert. Ihr zustandsloses Merkmal kann die Anwendung skalierbarer machen und die Implementierung von Caching-Richtlinien erleichtern, um die Benutzererfahrung und Leistung zu verbessern. In diesem Artikel werden wir vorstellen, was eine RESTful API ist und wie wir sie verwenden können.

Was ist eine API

Lassen wir für einen Moment beiseite, was eine API ist, und sprechen wir darüber, wie wir Informationen in unserem Leben übermitteln.

Wenn Sie Ihr Geld dem Ladenbesitzer geben und ihm sagen, dass Sie Batterien kaufen möchten, nimmt der Besitzer das Geld entgegen, sucht die Batterien im Regal und gibt sie Ihnen. Eine Transaktion zum Kauf einer Batterie ist erfolgreich abgeschlossen.

Computer-Software hingegen erledigt dies über APIs. Beginnen wir mit der Definition von Wikipedia:

Eine Anwendungsprogrammierschnittstelle (API) ist eine Möglichkeit, wie zwei oder mehr Computerprogramme miteinander kommunizieren können. Es handelt sich um eine Art Software-Schnittstelle, die anderen Softwareteilen einen Dienst anbietet.

Software A stellt eine Anfrage an Software B über die API, und Software B gibt die Antwort nach Abfrage ihrer Ressourcen über die API an A zurück.

Software A, die eine Anfrage an Software B über die API stellt, ist wie Sie, die Ihrem Chef sagen, dass Sie eine Batterie benötigen, und Software B, die die Daten an Software A zurückgibt, ist wie Ihr Chef, der die Batterie findet und Ihnen gibt.

Dieser Prozess erfordert nicht, dass Software B weiß, warum Software A die Daten möchte, genauso wie ein Ladenbesitzer Sie nicht fragen würde, warum Sie die Batterie gekauft haben. Software A muss auch nicht wissen, wie Software B die Daten gefunden hat, genauso wie Sie den Besitzer nicht fragen würden, wo die Batterien gekauft wurden, als Sie sie kauften. Jede Software gibt Informationen über APIs aneinander weiter, und jede macht ihre eigene Sache, wodurch die Programmierwelt geordnet und zuverlässig wird.

Was ist eine RESTful API

Roy Fielding definierte REST (Representational State Transfer) in seiner Dissertation von 2000, "Architectural Styles and Web-Based Software Architecture Design", und der REST-Architekturstil definiert sechs Leitprinzipien. Ein System, das einige oder alle dieser Prinzipien erfüllt, wird locker als RESTful bezeichnet.

(Quelle: Seobility)

Prinzipien von RESTful APIs

Best Practices für RESTful APIs

Die Betonung einheitlicher Schnittstellen zwischen Komponenten ist ein Kernmerkmal, das den REST-Architekturstil von anderen webbasierten Stilen unterscheidet, und basierend auf diesem Merkmal werden hier Best Practices zusammengefasst, um Ihnen zu helfen, Ihre API besser zu gestalten.

Vermeiden Sie Verben im Pfadnamen

Verwenden Sie HTTP-Methoden, um das Verhalten der Ressourcenmanipulation auszudrücken, anstatt Verhaltensverben in Pfade zu definieren.

// Gut
curl -X GET http://httpbin.org/orders

// Schlecht
curl -X GET "http://httpbin.org/getOrders"

• Holen Sie sich die Ressourceninformationen für den angegebenen URI mit GET

// Repräsentiert das Abrufen aller Bestellinformationen für das aktuelle System
curl -X GET http://httpbin.org/orders

// Repräsentiert das Abrufen der Bestelldetailinformationen für die Bestellnummer 1
curl -X GET http://httpbin.org/orders/1

• Erstellen Sie eine Ressource vom angegebenen URI mit POST

 // Repräsentiert die Erstellung einer Ressource mit dem Namen order
curl -X POST http://httpbin.org/orders \
  -d '{"name": "awesome", region: "A"}' \

• Erstellen oder ersetzen Sie Ressourcen vollständig auf dem angegebenen URI mit PUT

 // Repräsentiert die Datenersetzung für eine Bestellung mit der ID 1
curl -X PUT http://httpbin.org/orders/1 \
  -d '{"name": "new awesome", region: "B"}' \

• PATCH führt ein teilweises Update einer Ressource durch

 // Repräsentiert die Änderung des Regionsfelds der Bestellung mit der ID 1, während der Rest der Daten unverändert bleibt
curl -X PATCH http://httpbin.org/orders/1 \
  -d '{region: "B"}' \

• Entfernen Sie eine Ressource durch Angabe eines URI mit DELETE

 // Repräsentiert das Löschen der Bestellung mit der ID 1
curl -X DELETE http://httpbin.org/orders/1

URIs verwenden die Pluralform

Wenn Sie die Singularform verwenden möchten, um den Zugriff auf eine bestimmte Art von Ressource anzuzeigen:

curl -X GET "http://httpbin.org/order"

Die Verwendung der Singularform könnte den Benutzer verwirren, dass es nur eine Bestellung im System gibt, aber die Verwendung der Pluralform macht das Verständnis viel flüssiger.

curl -X GET "http://httpbin.org/orders"

Gute Nutzung von HTTP-Statuscodes

Der HTTP-Standard definiert Statuscodes, die grob in die folgenden Kategorien eingeteilt werden können:

Durch die Verwendung von Standard-Statuscodes können Entwickler Probleme sofort identifizieren und die Zeit reduzieren, die benötigt wird, um verschiedene Arten von Fehlern zu finden.

Versionskontrolle

Da sich die Geschäftsanforderungen ändern, müssen die bereits online verfügbaren APIs höchstwahrscheinlich entsprechend angepasst werden. Wenn unsere APIs von Dritten verwendet werden, ist es offensichtlich unmöglich, jeden Client nach den Änderungen unserer APIs ändern zu lassen, daher ist es an der Zeit, das Konzept der API-Versionsverwaltung einzuführen, das die normale Nutzung historischer APIs sicherstellt und neue APIs iteriert, um neue Geschäftsanforderungen zu erfüllen.

Häufige Mittel der Versionskontrolle sind:

• Versionskontrolle über Pfade in Anfragen

// Anfrage an v1 API
curl  http://httpbin.org/v1/orders

// Anfrage an v2 API
curl  http://httpbin.org/v2/orders

• Versionskontrolle über Abfrageparameter

// Anfrage an v1 API
curl  http://httpbin.org/orders?version=v1

// Anfrage an v2 API
curl  http://httpbin.org/v2/orders?version=v2

• Versionskontrolle über Header

// Anfrage an v1 API
curl  http://httpbin.org/orders -H "custom-version: v1"

// Anfrage an v2 API
curl  http://httpbin.org/orders -H "custom-version: v2"

Wie APISIX RESTful APIs unterstützt

Apache APISIX ist ein dynamisches, Echtzeit-, Hochleistungs-API-Gateway. Es kann vor jedem RESTful API-Dienst laufen und Plugins verwenden, um neue Dienste hinzuzufügen und seine Funktionalität zu erweitern, was dem RESTful-Definition von Geschichtetem System entspricht. Darüber hinaus kann APISIX Ihnen auch helfen, Ihre Schnittstelle ohne Änderung des ursprünglichen Geschäftscodes zu konvertieren, sodass Ihre Schnittstelle die REST-Einschränkung von Einheitlicher Schnittstelle erfüllt, wodurch Ihre API besser der RESTful API-Spezifikation entspricht.

Geschichtetes System: Unterstützt die Trennung von Geschäftslogik und Sicherheitslogik

Sie können sich einfach auf die Implementierung der Geschäftslogik konzentrieren, die Sicherheitslogik der Schnittstelle kann den APISIX-Authentifizierungs-Plugins überlassen werden, z.B. key-auth. APISIX unterstützt eine Vielzahl von Authentifizierungs Plugins, nehmen wir zum Beispiel openid-connect, wie in der folgenden Abbildung gezeigt:

Wir können sehen, dass die Verwendung von APISIX (API-Gateway), um eine Schicht von Authentifizierungslogik vor unseren Geschäftsserver zu setzen, dazu dient, die Upstream-Dienste zu schützen, und dieses Architekturmuster kann eine gute Möglichkeit sein, Ihre Geschäftslogik von der Sicherheitslogik zu entkoppeln.

Geschichtetes System：Unterstützung für mehrere Lastausgleichsprotokolle

APISIX, als API-Gateway, kann zwischen der Client- und Server-Seite eingerichtet werden, um verschiedene Lastanforderungen zu erfüllen. Sie können sogar die Lastausgleichslogik anpassen.

Die unterstützten Lastausgleichsalgorithmen sind:

• roundrobin: Rundlaufausgleich mit Gewichtungen.
• chash: Konsistenter Hash.
• ewma: Wählt den Knoten mit der geringsten Latenz. Siehe EWMA Chart für weitere Details.
• least_conn: Wählt den Knoten mit dem niedrigsten Wert von (active_conn + 1) / weight. Hier ist eine aktive Verbindung eine Verbindung, die von der Anfrage verwendet wird und ähnlich dem Konzept in Nginx ist.
• Benutzerdefinierter Lastausgleicher, der über require("apisix.balancer.your_balancer") geladen wird

Einheitliche Schnittstelle: Machen Sie historische APIs RESTfuler

Für historische APIs, die schon lange existieren und nicht gut den RESTful API-Richtlinien folgen, können Sie die neue API über APISIX neu kapseln, um verschiedenen Geschäftsszenarien gerecht zu werden, ohne die ursprüngliche API-Logik zu ändern.

• Verwenden Sie proxy-rewrite, um Client-Anfragen umzuschreiben

Wie oben erwähnt, sollten wir keine Verben in unserem Pfad haben.

Wenn die historische API beispielsweise die /getOrder-Schnittstelle hat, können wir die API-Anfrage über das proxy-rewrite-Plugin an die historische API weiterleiten.

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {
        "proxy-rewrite": {
            "uri": "/getOrder",
            "scheme": "http",
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

Sie können das Plugin auch für API-Versionierungsoperationen verwenden.

• Verwenden Sie das response-rewrite Plugin, um serverseitige Antworten umzuschreiben

Wenn unsere historische API nicht standardisierte Antwortstatuscodes hat, können wir response-rewrite verwenden, um die Antwort zu proxen und den Antwortstatuscode zu ändern.

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {
        "response-rewrite": {
            "status_code": 201,
            "body": "{\"code\":\"ok\",\"message\":\"new json body\"}",
            "vars":[
                [ "status","==",200 ]
            ]
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

Das obige Beispiel repräsentiert eine Anfrage, um den Status von 200 auf 201 in der API-Anfrage an den Pfad /orders zu ändern.

Da APISIX sehr reichhaltige Plugins unterstützt, freue ich mich darauf, dass Sie weitere Möglichkeiten erkunden.

Zusammenfassung

Dieser Artikel führt ein, was eine API ist, was eine RESTful API ist und ihre Best Practices. Darüber hinaus führt dieser Artikel auch ein, wie man Geschäftslogik und Sicherheitslogik über APISIX trennt und wie man APISIX verwendet, um historische API-Dienste RESTfuler zu machen, ohne den ursprünglichen Geschäftscode zu ändern. Hoffentlich hilft Ihnen dieser Artikel, RESTful APIs besser zu verstehen.