Verständnis und Verwendung von REST-APIs

Es ist sehr wahrscheinlich, dass Sie auf den Begriff „REST-API“ gestoßen sind, wenn Sie daran gedacht haben, Daten aus einer anderen Quelle im Internet wie Twitter oder Github zu beziehen. Aber was ist eine REST-API? Was kann es für Sie tun? Wie benutzt man es?

In diesem Artikel erfahren Sie alles, was Sie über REST-APIs wissen müssen, um API-Dokumentationen lesen und effektiv nutzen zu können.

Was ist eine REST-API

Nehmen wir an, Sie suchen Videos über Batman auf Youtube. Sie öffnen Youtube, geben „Batman“ in ein Suchfeld ein, drücken die Eingabetaste und sehen eine Liste mit Videos über Batman. Eine REST-API funktioniert ähnlich. Sie suchen nach etwas und erhalten eine Ergebnisliste von dem Dienst, bei dem Sie die Anfrage gestellt haben.

Eine API ist eine Anwendungsprogrammierschnittstelle. Es handelt sich um eine Reihe von Regeln, die es Programmen ermöglichen, miteinander zu kommunizieren. Der Entwickler erstellt die API auf dem Server und ermöglicht dem Client, mit ihr zu kommunizieren.

REST bestimmt, wie die API aussieht. Es steht für „Representational State Transfer“. Es handelt sich um eine Reihe von Regeln, die Entwickler befolgen, wenn sie ihre API erstellen. Eine dieser Regeln besagt, dass Sie in der Lage sein sollten, ein Datenelement (als Ressource bezeichnet) abzurufen, wenn Sie auf eine bestimmte URL verlinken.

Jede URL wird als Anforderung bezeichnet, während die an Sie zurückgesendeten Daten als Antwort bezeichnet werden.

Die Anatomie einer Anfrage

Es ist wichtig zu wissen, dass eine Anfrage aus vier Dingen besteht:

1. Der Endpunkt
2. Die Methode
3. Die Überschriften
4. Die Daten (oder Körper)

Der Endpunkt (oder die Route) ist die URL, die Sie anfordern. Es folgt dieser Struktur:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

Der Stammendpunkt ist der Ausgangspunkt der API, von der Sie anfordern. Der Root-Endpunkt der API von Github ist https://api.github.com , während der Root-Endpunkt der API von Twitter https://api.twitter.com ist.

Der Pfad bestimmt die Ressource, die Sie anfordern. Stellen Sie es sich wie einen automatischen Anrufbeantworter vor, der Sie auffordert, die 1 für einen Dienst, die 2 für einen anderen Dienst, die 3 für einen weiteren Dienst und so weiter zu drücken.

Sie können auf Pfade zugreifen, genauso wie Sie auf Teile einer Website verlinken können. Um beispielsweise eine Liste aller Beiträge zu erhalten, die unter „JavaScript“ im Smashing Magazine getaggt sind, navigieren Sie zu https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ ist der Root-Endpunkt und /tag/javascript ist der Pfad.

Um zu verstehen, welche Pfade Ihnen zur Verfügung stehen, müssen Sie die API-Dokumentation durchsehen. Angenommen, Sie möchten eine Liste der Repositories eines bestimmten Benutzers über die API von Github abrufen. Die Dokumentation sagt Ihnen, dass Sie dazu den folgenden Pfad verwenden sollen:

 /users/:username/repos

Jeder Doppelpunkt ( : ) auf einem Pfad bezeichnet eine Variable. Sie sollten diese Werte durch tatsächliche Werte ersetzen, wenn Sie Ihre Anfrage senden. In diesem Fall sollten Sie :username durch den tatsächlichen Benutzernamen des gesuchten Benutzers ersetzen. Wenn ich nach meinem Github-Konto suche, ersetze ich :username durch zellwk .

Der Endpunkt, um eine Liste meiner Repos auf Github zu erhalten, ist dieser:

 https://api.github.com/users/zellwk/repos

Der letzte Teil eines Endpunkts sind Abfrageparameter . Technisch gesehen sind Abfrageparameter kein Teil der REST-Architektur, aber Sie werden sehen, dass viele APIs sie verwenden. Um Ihnen zu helfen, vollständig zu verstehen, wie man APIs liest und verwendet, werden wir auch darüber sprechen. Abfrageparameter geben Ihnen die Möglichkeit, Ihre Anfrage mit Schlüssel-Wert-Paaren zu ändern. Sie beginnen immer mit einem Fragezeichen ( ? ). Jedes Parameterpaar wird dann wie folgt durch ein kaufmännisches Und ( & ) getrennt:

 ?query1=value1&query2=value2

Wenn Sie versuchen, eine Liste der Repositories eines Benutzers auf Github abzurufen, fügen Sie Ihrer Anfrage drei mögliche Parameter hinzu, um die Ihnen angezeigten Ergebnisse zu ändern:

Wenn Sie eine Liste der Repositories erhalten möchten, in die ich kürzlich gepusht habe, können Sie sort auf push setzen.

 https://api.github.com/users/zellwk/repos?sort=pushed

Woher wissen Sie, ob dieser Endpunkt funktioniert? Nun, es ist Zeit, es zu versuchen!

Testen von Endpunkten mit curl

Sie können eine Anfrage mit jeder Programmiersprache senden. JavaScript-Benutzer können Methoden wie die Fetch-API und die Ajax-Methode von jQuery verwenden; Ruby-Benutzer können Rubys Net::HTTP-Klasse verwenden, Python-Benutzer können Python-Anforderungen verwenden; und so weiter.

Für diesen Artikel verwenden wir das Befehlszeilendienstprogramm namens cURL. Wir verwenden cURL, weil API-Dokumentationen normalerweise mit Bezug auf cURL geschrieben werden. Wenn Sie verstehen, wie man cURL verwendet, werden Sie keine Probleme haben, API-Dokumentationen zu verstehen. Dann können Sie ganz einfach Anfragen in Ihrer bevorzugten Sprache durchführen.

Bevor Sie fortfahren, sollten Sie sicherstellen, dass Sie cURL auf Ihrem Computer installiert haben. Öffnen Sie Ihr Terminal und geben Sie curl -version . Dieser Befehl überprüft die Version von cURL, die Sie auf Ihrem System installiert haben.

 curl --version

Wenn Sie cURL nicht installiert haben, erhalten Sie die Fehlermeldung „Befehl nicht gefunden“. Wenn Sie diesen Fehler erhalten, müssen Sie curl installieren, bevor Sie fortfahren.

Um cURL zu verwenden, geben Sie curl ein, gefolgt von dem Endpunkt, den Sie anfordern. Um beispielsweise den Root-Endpunkt von Github abzurufen, geben Sie Folgendes ein:

 curl https://api.github.com

Sobald Sie die Eingabetaste gedrückt haben, sollten Sie eine Antwort von Github erhalten, die wie folgt aussieht:

Um eine Liste der Repositorys eines Benutzers zu erhalten, ändern Sie den Endpunkt auf den richtigen Pfad, wie oben beschrieben. Um eine Liste meiner Repositorys zu erhalten, können Sie diesen Befehl verwenden:

 curl https://api.github.com/users/zellwk/repos

Wenn Sie Abfrageparameter mit cURL einschließen möchten, stellen Sie sicher, dass Sie einen umgekehrten Schrägstrich ( \ ) vor dem ? und = Zeichen. Das liegt daran ? und = sind Sonderzeichen in der Kommandozeile. Sie müssen \ vor ihnen verwenden, damit die Befehlszeile sie als normale Zeichen interpretiert:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Versuchen Sie es mit einem der beiden Befehle und führen Sie eine Anfrage aus! Sie erhalten eine ähnliche Antwort wie bei Githubs Root-Endpont (aber mit viel mehr Daten).

JSON

JSON (JavaScript Object Notation) ist ein gängiges Format zum Senden und Anfordern von Daten über eine REST-API. Die Antwort, die Github an Sie zurücksendet, ist ebenfalls als JSON formatiert.

Ein JSON-Objekt sieht aus wie ein JavaScript-Objekt. In JSON muss jede Eigenschaft und jeder Wert wie folgt in doppelte Anführungszeichen eingeschlossen werden:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Zurück zur Anatomie einer Anfrage

Sie haben gelernt, dass eine Anfrage aus vier Teilen besteht.

1. Der Endpunkt
2. Die Methode
3. Die Überschriften
4. Die Daten (oder Körper)

Lassen Sie uns den Rest durchgehen, was eine Anfrage ausmacht.

Die Methode

Die Methode ist die Art der Anfrage, die Sie an den Server senden. Sie können aus diesen fünf Typen unten wählen:

• GET
• POST
• PUT
• PATCH
• DELETE

Diese Methoden geben der von Ihnen gestellten Anfrage eine Bedeutung. Sie werden verwendet, um vier mögliche Aktionen auszuführen: Create , Read , Update und Delete (CRUD).

Die API teilt Ihnen mit, welche Anforderungsmethode für jede Anforderung verwendet werden soll. Um beispielsweise eine Liste der Repositories eines Benutzers zu erhalten, benötigen Sie eine GET -Anfrage:

Eine GET-Anforderung ist erforderlich, um eine Liste von Repositories von einem Benutzer zu erhalten. Um ein neues Github-Repository zu erstellen, benötigen Sie eine POST Anfrage:

Sie können die Anforderungsmethode in cURL festlegen, indem Sie -X oder --request , gefolgt von der Anforderungsmethode. Dieser Befehl unten versucht, ein Repository über cURL zu erstellen:

 curl -X POST https://api.github.com/user/repos

Versuchen Sie, diese Anfrage auszuführen. Sie erhalten eine Antwort, die Ihnen mitteilt, dass eine Authentifizierung erforderlich ist. (Mehr zur Authentifizierung später).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Die Header

Header werden verwendet, um Informationen sowohl für den Client als auch für den Server bereitzustellen. Es kann für viele Zwecke verwendet werden, z. B. zur Authentifizierung und Bereitstellung von Informationen über den Inhalt des Körpers. Eine Liste gültiger Header finden Sie in der HTTP-Header-Referenz von MDN.

HTTP-Header sind Property-Value-Paare , die durch einen Doppelpunkt getrennt sind. Das folgende Beispiel zeigt einen Header, der den Server anweist, JSON-Inhalt zu erwarten.

 "Content-Type: application/json". Missing the opening ".

Sie können HTTP-Header mit curl über die Option -H oder --header . Um den obigen Header an die API von Github zu senden, verwenden Sie diesen Befehl:

 curl -H "Content-Type: application/json" https://api.github.com

(Hinweis: Der Content-Type-Header ist keine Voraussetzung für das Funktionieren der Github-API. Dies ist nur ein Beispiel, um zu veranschaulichen, wie ein Header mit cURL verwendet wird).

Um die von Ihnen gesendeten Header anzuzeigen, können Sie die Option -v oder --verbose , während Sie die Anfrage senden, wie folgt:

 curl -H "Content-Type: application/json" https://api.github.com -v 

* bezieht sich hier auf zusätzliche Informationen, die von cURL bereitgestellt werden. > bezieht sich auf Anforderungsheader und < bezieht sich auf die Antwortheader.

Die Daten (oder „Körper“)

Die Daten (manchmal auch als „Body“ oder „Message“ bezeichnet) enthalten Informationen, die Sie an den Server senden möchten. Diese Option wird nur bei POST -, PUT -, PATCH oder DELETE -Anforderungen verwendet.

Um Daten über cURL zu senden, können Sie die Option -d oder --data :

 curl -X POST <URL> -d property1=value1

Um mehrere Datenfelder zu senden, können Sie mehrere -d -Optionen erstellen:

 curl -X POST <URL> -d property1=value1 -d property2=value2

Wenn es sinnvoll ist, können Sie Ihre Anfrage in mehrere Zeilen \ , um sie besser lesbar zu machen:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Wenn Sie wissen, wie man einen Server hochfährt, können Sie eine API erstellen und Ihre eigenen Daten testen. Wenn Sie es nicht wissen, aber mutig genug sind, es zu versuchen, können Sie diesem Artikel folgen, um zu erfahren, wie Sie einen Server mit Node, Express und MongoDB erstellen

Wenn Sie Ihren Server nicht hochfahren möchten, können Sie zu Requestbin.com gehen ( kostenlos! ) und auf „Endpunkt erstellen“ klicken. Sie erhalten eine URL, die Sie zum Testen von Anforderungen verwenden können, z. B. https://requestb.in/1ix963n1 , wie im Bild unten gezeigt.

Stellen Sie sicher, dass Sie Ihren eigenen Anfragekorb erstellen, wenn Sie Ihre Anfrage testen möchten. Anfrage-Bins bleiben nur 48 Stunden nach ihrer Erstellung geöffnet. Wenn Sie diesen Artikel lesen, wird der Behälter, den ich oben erstellt habe, längst verschwunden sein.

Versuchen Sie nun, einige Daten an Ihr Anforderungsfach zu senden, und aktualisieren Sie dann die Webseite Ihres Fachs. Sie sehen einige Daten wie diese:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

Standardmäßig sendet cURL Daten so, als ob sie durch „Formularfelder“ auf einer Seite gesendet würden. Wenn Sie JSON-Daten senden möchten, müssen Sie den Content-Type auf application/json setzen und Ihre Daten wie folgt als JSON-Objekt formatieren:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

Und das ist (fast!) alles, was Sie über den Aufbau einer Anfrage wissen müssen.

Erinnern Sie sich, als Sie versuchten, eine POST -Anfrage über die Github-API zu senden, erhielten Sie eine Meldung mit der Aufschrift „Authentifizierung erforderlich“? Nun, das liegt daran, dass Sie nicht berechtigt sind, die POST -Anforderung auszuführen!

Authentifizierung

Sie würden niemandem erlauben, ohne Ihre Erlaubnis auf Ihr Bankkonto zuzugreifen, oder? Auf der gleichen Linie haben Entwickler Maßnahmen ergriffen, um sicherzustellen, dass Sie Aktionen nur dann ausführen, wenn Sie dazu autorisiert sind. Dadurch wird verhindert, dass andere sich als Sie ausgeben.

Da POST , PUT , PATCH und DELETE -Anforderungen die Datenbank verändern, verstecken Entwickler sie fast immer hinter einer Authentifizierungsmauer. In einigen Fällen erfordert eine GET -Anforderung auch eine Authentifizierung (z. B. wenn Sie auf Ihr Bankkonto zugreifen, um Ihren aktuellen Kontostand zu überprüfen).

Im Internet gibt es zwei Möglichkeiten, sich zu authentifizieren:

1. Mit Benutzername und Passwort (auch Basisauthentifizierung genannt)
2. Mit einem geheimen Token

Die geheime Token-Methode beinhaltet oAuth, mit dem Sie sich bei sozialen Netzwerken wie Github, Google, Twitter, Facebook usw. authentifizieren können.

In diesem Artikel erfahren Sie nur, wie Sie die Basisauthentifizierung mit einem Benutzernamen und einem Passwort verwenden. Wenn Sie daran interessiert sind, sich mit oAuth zu authentifizieren, empfehle ich Ihnen, „What You Need To Know About OAuth2 And Logging In With Facebook“ von Zack Grossbart zu lesen.

Um eine einfache Authentifizierung mit cURL durchzuführen, können Sie die Option -u gefolgt von Ihrem Benutzernamen und Passwort wie folgt verwenden:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Versuchen Sie, sich in der obigen Anfrage mit Ihrem Benutzernamen und Passwort zu authentifizieren. Sobald die Authentifizierung erfolgreich ist, ändert sich die Antwort von „Requires authentication“ zu „Problems parsing JSON“.

Dies liegt daran, dass Sie dem Server noch keine Daten zur Verfügung stellen müssen (die von allen POST -, PUT -, PATCH und DELETE -Anforderungen benötigt werden).

Mit dem bisher erworbenen Wissen sollten Sie in der Lage sein, den obigen Code zu bearbeiten, um ein Github-Repository über Ihre cURL zu erstellen. Ich überlasse es Ihnen, es selbst zu versuchen!

Lassen Sie uns nun über HTTP-Statuscodes und Fehlermeldungen sprechen.

HTTP-Statuscodes und Fehlermeldungen

Einige der Nachrichten, die Sie zuvor erhalten haben, wie „Authentifizierung erforderlich“ und „Probleme beim Analysieren von JSON“, sind Fehlermeldungen. Sie erscheinen nur, wenn etwas mit Ihrer Anfrage nicht stimmt. Mit HTTP-Statuscodes können Sie den Status der Antwort schnell erkennen. Die Bandbreite reicht von 100+ bis 500+. Im Allgemeinen folgen die Zahlen den folgenden Regeln:

1. 200+ bedeutet, dass die Anfrage erfolgreich war .
2. 300+ bedeutet, dass die Anfrage an eine andere URL umgeleitet wird
3. 400+ bedeutet, dass ein vom Client ausgehender Fehler aufgetreten ist
4. 500+ bedeutet, dass ein vom Server ausgehender Fehler aufgetreten ist

Sie können den Status einer Antwort mit der Verbose-Option ( -v oder --verbose ) oder der Head-Option ( -I oder --head ) debuggen.

Wenn Sie beispielsweise versucht haben, -I zu einer POST -Anfrage hinzuzufügen, ohne Ihren Benutzernamen und Ihr Passwort anzugeben, erhalten Sie einen 401-Statuscode (Nicht autorisiert):

Wenn Ihre Anfrage ungültig ist, weil Ihre Daten falsch sind oder fehlen, erhalten Sie normalerweise einen 400-Statuscode (Bad Request).

Weitere Informationen zu bestimmten HTTP-Statuscodes finden Sie in der HTTP-Statusreferenz von MDN.

API-Versionen

Entwickler aktualisieren ihre APIs von Zeit zu Zeit. Manchmal kann sich die API so stark ändern, dass der Entwickler beschließt, seine API auf eine andere Version zu aktualisieren. Wenn dies passiert und Ihre Anwendung abstürzt, liegt dies normalerweise daran, dass Sie Code für eine ältere API geschrieben haben, Ihre Anfrage jedoch auf die neuere API verweist.

Sie können eine bestimmte API-Version auf zwei Arten anfordern. Welche Methode Sie wählen, hängt davon ab, wie die API geschrieben ist.

Diese beiden Wege sind:

1. Direkt im Endpunkt
2. In einem Anforderungsheader

Twitter verwendet beispielsweise die erste Methode. Zum Zeitpunkt des Verfassens dieses Artikels befindet sich die Twitter-API in Version 1.1, was durch ihren Endpunkt deutlich wird:

 https://api.twitter.com/1.1/account/settings.json

Github hingegen verwendet die zweite Methode. Zum Zeitpunkt des Verfassens dieses Artikels befindet sich die API von Github in Version 3, und Sie können die Version mit einem Accept -Header angeben:

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Einpacken

In diesem Artikel haben Sie gelernt, was eine REST-API ist und wie Sie mit cURL eine Anfrage mit den Methoden GET , POST , PUT , PATCH und DELETE ausführen. Außerdem haben Sie gelernt, wie Sie Ihre Anfragen mit der Option -u authentifizieren und was HTTP-Status bedeuten.

Ich hoffe, dieser Artikel hat Ihnen geholfen, genug über REST-APIs zu lernen, und Sie können sie beim Erstellen Ihrer Anwendungen fließend verwenden. Fühlen Sie sich frei, in meinem Blog vorbeizuschauen oder unten Ihre Kommentare zu hinterlassen, wenn Sie Fragen haben.