Eine schmerzlose Einführung in die Arbeit mit APIs

Typischer API-Aufruf

Wenn Sie irgendwo in der Nähe der Webentwicklungsbranche arbeiten, werden Sie mit Sicherheit diese drei berüchtigten Buchstaben hören: A. P. I.

Sie werden von Anfängern und Experten gleichermaßen herumgeworfen:

„Warum muss ich eine API aufrufen? Hat es eine Nummer? "

"Ein einfacher Aufruf dieser Drittanbieter-API reicht hier aus."

"Wir erstellen Ihnen eine RESTful-API. Stellen Sie sicher, dass Ihr neues System gut mit anderen Diensten zusammenarbeitet. “

Während APIs zunächst einschüchternd wirken, können sie Ihr Leben als Entwickler buchstäblich verändern.

Warum? Wenn Sie lernen, APIs richtig zu verwenden, können Sie Ihren Entwicklungsworkflow vereinfachen, beschleunigen und stärken. Das Erstellen oder Integrieren von APIs bringt sowohl für den Kunden als auch für Sie Vorteile.

Als Entwickler hört man oft den Rat: "erfinde das Rad nicht neu".

Abgesehen von Witzen spielen APIs eine wichtige Rolle, wenn Sie das Rad nicht neu erfinden. Das Verständnis der Grundlagen von APIs ist für moderne Webentwickler von entscheidender Bedeutung. In diesem Beitrag helfe ich Ihnen dabei. Wir decken ab:

  • Die Vorteile einer API
  • Was ist eine API wirklich?
  • Welche Arten von APIs gibt es
  • Praktische Anwendungsfälle

Tauchen wir doch mal ein!

Warum APIs verwenden?

Verbessern Sie Ihre Entwicklerfähigkeiten mit APIs

Einer der ersten großen Meilensteine ​​meiner Programmierkarriere war das richtige Verständnis von APIs. Ich benutze sie immer noch jeden Tag.

Lassen Sie mich zunächst überzeugen, dass es sich lohnt, APIs zu verstehen, bevor ich auf das Wesentliche eingehe. Wieso das?

Weil das Erlernen der Verwendung von APIs Ihre Entwicklungseffizienz erheblich steigert.

Erstens können Sie vorhandene Logik nutzen, die Sie nicht schreiben müssen. Einige Dinge, die Sie möglicherweise nicht selbst codieren können! Um als Entwickler wertvolle Zeit zu sparen, ist es wichtig, eine Vorstellung davon zu haben, wie die API-Landschaft aussieht.

Zweitens wurden viele Entwicklungsprobleme, auf die Sie stoßen, bereits von jemandem vor Ihnen gelöst.

Diese vorhandenen Lösungen können FaaS, Bibliotheken, Webdienste, SDKs und Inhalts-APIs sein. Unabhängig von ihrer Form benötigen Sie höchstwahrscheinlich eine API, um mit ihnen zu interagieren.

Was genau sind APIs?

Web-APIs, Bild von MS

Die offizielle (entmutigende) Definition lautet wie folgt:

Bei der Computerprogrammierung besteht eine Anwendungsprogrammierschnittstelle (Application Programming Interface, API) aus einer Reihe von Unterprogrammdefinitionen, Protokollen und Werkzeugen zum Erstellen von Anwendungssoftware. Im Allgemeinen handelt es sich um eine Reihe klar definierter Kommunikationsmethoden zwischen verschiedenen Softwarekomponenten. Eine gute API erleichtert die Entwicklung eines Computerprogramms, indem alle Bausteine ​​bereitgestellt werden, die dann vom Programmierer zusammengestellt werden.

Ein bisschen schwer, oder? Lassen Sie uns die akademische Prosa etwas leiser machen. Hier ist eine freundlichere, hausgemachte API-Definition:

Einfach ausgedrückt, eine API deklariert eine Schnittstelle, damit Sie mit ihrer Logik interagieren können, ohne wissen zu müssen, was unter der Haube passiert. Diese Definition gilt für alle Sprachen, Protokolle oder Umgebungen, in denen Sie sich befinden. Die einzige Voraussetzung ist, dass dies auf programmatischer Ebene geschieht. Mehr dazu weiter unten.

Um APIs noch besser zu beleuchten, listen wir auf, was sie NICHT sind:

  • Eine API ist nicht unbedingt ein externer Dienst. Beispielsweise können Sie Bibliotheken direkt in Ihre Lösung einbinden ODER über eine API verwenden.
  • Eine API ist nicht nur eine Schnittstelle. Es ist sowohl die Spezifikation / das Format als auch die Implementierung.
  • Eine API ist keine grafische Benutzeroberfläche. Eine API führt keine Interaktionen auf grafischer Ebene aus. Es arbeitet ausschließlich auf der Programmebene. Dies kann entweder über eine Programmiersprache oder ein Kommunikationsprotokoll erfolgen.

Verschiedene Arten von APIs

Es werden nicht alle APIs gleich erstellt.

Obwohl sie meistens dasselbe Ziel verfolgen, erreichen einige es viel besser als andere. Da dies ein reibungsloses Intro sein soll, werde ich nicht darauf eingehen, was eine API besser macht als andere.

Denken Sie daran, dass die Menschen beim Erstellen von APIs sehr unterschiedliche Ansätze verfolgen. Wenn Sie dieses Thema interessiert, informieren Sie sich bei Google über „API-Entwurfsmuster“ und „API-Paradigmen“. Oder beginnen Sie einfach mit diesem übersichtlichen Einstiegsartikel. :)

Endpunkte

Das Ziel von APIs ist es, Ihnen das Leben als Entwickler zu erleichtern. Wie haben sie das gemacht?

Durch Zusammenfassen von Merkmalen / Funktionen, die zusammengesetzt wurden, und Anzeigen dieser Funktionen über Endpunkte. Dies sind normalerweise URL-Muster, die für die Kommunikation mit der API verwendet werden.

Diese Endpunkte sind die einzige Möglichkeit, mit einer API zu interagieren. Jeder Endpunkt hat ein bestimmtes Format für Anforderungen und Antworten. Dieses Format ist normalerweise in der API-Dokumentation definiert.

Endpunkte können einfache Funktionen sein. Sie können auch aus vielen Funktionen bestehen, die andere APIs usw. aufrufen.

Der entscheidende Punkt hierbei ist, dass die zugrunde liegende Logik dieser Funktionen vollständig abstrahiert ist. Sie müssen nicht wissen, was in ihnen vor sich geht, um sie zu verwenden.

Solange Sie das richtige Format verwenden, können Sie diese verwenden. Hier ist „verbrauchen“ eine ausgefallene Art zu sagen, „Teile davon für Ihre Anwendung zu verwenden“.

Das Fazit lautet: Eine API ist wie jede Schnittstelle.

Zum Vergleich: Ein Lichtschalter schaltet ein Licht ein, unabhängig davon, ob Sie wissen, wie elektrische Ströme funktionieren oder nicht. (Als junger Erwachsener habe ich auch gelernt, dass Sie die Stromrechnung bezahlen müssen, damit sie funktioniert. Aber das ist eine andere Geschichte.)

Verwendung von APIs: praktische Beispiele

Tauschen wir die Theorie jetzt gegen eine einfache Praxis aus.

API-Dokumentation lesen

Ich möchte begriffliche Erklärungen nicht zu sehr überdehnen. Analysieren wir stattdessen eine wirklich einfache API. Wir werden sehen, wie es in einem realen Szenario funktioniert. Dazu verwenden wir das native JavaScript Math-Objekt. Sie können die Dokumentation hier lesen.

In den Dokumenten wird erläutert, wie jede Funktion des Math-Objekts das Eingabeformat beschreibt. Zum Beispiel könnte es eine Zahl oder ein Array von Zahlen sein.

In den Dokumenten wird auch das Format der Ausgabe beschrieben.

Beachten Sie, wie nichts über die Logik erwähnt wird, die zum Ausführen dieser Funktionen verwendet wird.

Wenn Sie beispielsweise Ihre Browserkonsole starten und Math.sqrt eingeben (ohne die Funktion auszuführen), sehen Sie Folgendes:

ƒ sqrt () {[native code]}

Das ist der Geist einer API. Unabhängig davon, ob Sie eine der APIs Ihres Betriebssystems oder eine webbasierte API aufrufen, bleiben diese Grundsätze bestehen.

Grundlegende Beispiele für API-Anwendungsfälle

Es gibt eine Menge Dinge, die mit bekannten API-Anbietern gemacht werden können.

Die Google Maps-API wird häufig verwendet, um eine bessere Nutzererfahrung mit Daten zu erzielen, die auf Echtzeit-Mapping und Verkehrssignalen basieren. Die Twitter-API kann verwendet werden, um gezielte Tweets in Echtzeit zu filtern und anzuzeigen.

Ich vermute, viele von Ihnen interessieren sich mehr für webbasierte APIs als für alles andere. Tauchen wir also in spezifische Anwendungsfälle ein.

In unseren Beispielen verwenden wir Postman. Dieser Rest Client ist an eine Webumgebung gebunden, aber solche Tools gibt es normalerweise auch in anderen Umgebungen. Es lohnt sich, einen Blick auf die für eine bestimmte Umgebung bereitgestellten Tools zu werfen, bevor Sie anfangen, mit ihnen zu spielen. Dies kann Ihnen viel Zeit sparen.

Wenn Sie mitmachen möchten, müssen Sie den Postman-Client herunterladen.

Verwendung einer öffentlichen API zum Abrufen von Daten

Unser erstes Beispiel wird recht einfach sein, aber immer noch interessanter als das Mathe-Beispiel.

Wir werden die Hunde-API verwenden!

Es ist nicht nur eine witzige API, sondern erfordert auch keine Authentifizierung.

Außerdem handelt es sich um eine HTTP-REST-API. Dies bedeutet, dass es sich um eine webbasierte API handelt. Da dies an diese Umgebung gebunden ist, müssen wir einige der Protokollspezifitäten einhalten.

In diesem Fall bedeutet dies die Verwendung von HTTP-Verben wie GET, PUT, POST, DELETE.

In unserem Beispiel halten wir die Dinge einfach und verwenden nur das GET-Verb. Die API unterstützt sowieso nichts anderes. Mit den meisten öffentlichen APIs können Sie nur Daten konsumieren und keine veröffentlichen.

Lassen Sie uns Postman starten und sehen, wie die Benutzeroberfläche aussieht.

Meine Benutzeroberfläche verwendet das dunkle Thema, daher kann es leicht von Ihrem abweichen.

Hier müssen zunächst möglicherweise viele Informationen verdaut werden. Beginnen wir also mit dem VERB und der URL.

Das Standardverb sollte GET sein. In diesem Fall können Sie dies beibehalten und die folgende URL eingeben: https://dog.ceo/api/breeds/list/all

Drücken Sie "Senden" und schlagen Sie! Sie sollten eine Antwort mit den entsprechenden Daten erhalten. Voilà! Sie haben gerade Ihren ersten API-Aufruf durchgeführt.

In diesem Beispiel verwenden wir keine der empfangenen Daten. Aber du kommst auf die Idee. Sie können Ihrem Benutzer verschiedene Hunderassen anzeigen und ein Bild einer bestimmten Rasse anzeigen, wenn er darauf klickt.

Sie können mit den verschiedenen Routen in der Dokumentation spielen, um sich mit der Umgebung vertraut zu machen.

Coole Tatsache: Dieses kleine Projekt ist auch Open Source, so dass Sie hier einen Blick unter die Haube werfen können.

Behandlung der Authentifizierung mit einer privaten API

Hoffentlich verstehen Sie jetzt besser, wie verschiedene Teile in Bezug auf APIs zusammenarbeiten. Führen Sie ein komplexeres Lernprogramm durch, das die Authentifizierung umfasst. Ich werde hier eine der APIs "meiner" eigenen Anwendungen verwenden.

Hier verwenden wir nur Code für die Interaktion mit der Snipcart-API. Sie können Postman schließen, aber halten Sie es bereit. Es ist gut, ein solches Tool zu verwenden, wenn Sie mit einer API beginnen.

Das Ziel wird es sein, ein einfaches Befehlszeilenschnittstellentool (Command Line Interface, CLI) zu erstellen, mit dem Kunden Rabatte für die einmalige Verwendung erhalten. Diese Rabatte werden über eine API generiert. All dies geschieht vollständig auf Ihrem Computer.

Erstellen Sie einen neuen Ordner für dieses Projekt. Verwenden Sie npm init im Ordner und starten Sie Ihren Texteditor.

Erstellen Sie nun eine index.js-Datei und öffnen Sie die package.json-Datei. Fügen Sie die folgenden Zeilen in das Objekt der obersten Ebene ein:

"bin": {"discount": "./index.js"}

Wir werden auch das Kommandopaket benötigen, um Eingaben vom Client zu analysieren. Führen Sie npm install --save commander im aktuellen Ordner aus.

Wir werden auch eine kleine Bibliothek verwenden, um IDs zu erstellen. Sie können es mit npm install --save shortid installieren.

Lassen Sie uns auch npm install --save request lib ausführen, während wir gerade dabei sind. Dies erleichtert uns das Tätigen von HTTP-Anrufen. Kehren Sie in Ihre index.js-Datei zurück und fügen Sie diesen Code ein:

Konzentrieren wir uns hier nur auf die Anforderungsfunktion.

Hier führen wir den externen API-Aufruf an Snipcart durch. Sie sehen, wir übergeben die Methode: "POST" an die Methode. Dies liegt daran, dass wir Daten an die Snipcart-API POSTEN möchten. Durch Angabe dieser Methode ordnet die API die Aktion korrekt zu. Auf diese Weise kann der Hauptteil der Anforderung gelesen werden, in dem sich die Rabattdaten befinden.

Eine interessante API-Funktion, die wir noch nicht verwendet haben, ist die Authentifizierung.

Unsere anderen Beispiele betrafen alle öffentliche APIs. Diese erfordern keine Authentifizierung.

Im wirklichen Leben erfordern die meisten APIs, die Sie verwenden werden, wahrscheinlich eine Authentifizierung. Dies ist ein Standardmuster in der API-Welt. Unsere Kunden würden sich nicht freuen, wenn wir jemandem erlauben würden, Rabatte auf ihren Shop zu gewähren! ;)

Zu unserem Zweck übergeben wir den API-Schlüssel direkt in der Anfrage.

Hurra - der Server erkennt uns! Es kann dann die Anforderung ausführen, die nur für unser Konto gültig ist.

Wenn Sie unsere kleine App testen möchten, können Sie npm install -g im Projektverzeichnis ausführen. Führen Sie dann einfach Rabatte x aus, um die Rabatte x-mal zu erstellen.

Sie können in Ihrem Snipcart-Dashboard (für immer kostenlose Konten im Testmodus) nachsehen, ob die Rabatte ordnungsgemäß erstellt wurden.

Sie können sich vorstellen, wie mächtig das sein kann. Wenn Sie 200 dieser Rabatte erstellen müssten, würde dies viel zu viel Zeit in Anspruch nehmen, um dies über unsere Benutzeroberfläche zu tun.

Wenn Sie mit der Funktionsweise von APIs vertraut sind, können Sie dies in wenigen Minuten erledigen. Der Code kann auch wiederverwendet werden. Wenn Sie also in einem Monat dasselbe tun müssen, sind Sie bereits festgelegt.

Gedanken schließen

Ich hoffe aufrichtig, dass Ihnen dieser Primer dabei geholfen hat, besser zu verstehen, was APIs sind und wie Sie sie in Ihrem Entwicklungsworkflow nutzen können.

Ein paar Imbissbuden:

  • APIs beschleunigen Ihre Geschwindigkeit und erweitern Ihren Entwicklungsumfang. Benutze sie!
  • APIs sind NICHT unbedingt an das Web-Ökosystem gebunden. Sie werden sie überall sehen.
  • Überprüfen Sie immer die Dokumentation der API, die Sie verwenden möchten.
  • Suchen Sie immer nach vorhandenen Tools (APIs oder anderen) in Ihrem Ökosystem, bevor Sie mit dem Code beginnen.

Unser letztes Beispiel ist nicht wirklich "produktionsbereit". Aber es gibt Ihnen eine gute Vorstellung davon, wie die Dinge in einem realen Anwendungsfall aussehen könnten.

Es gibt eine Menge Dinge, die wir hätten verbessern können. Zum Beispiel:

  • Lassen Sie den Benutzer den Rabatttyp auswählen
  • Wir könnten die erstellten Codes auch direkt in derselben Funktion per E-Mail senden, anstatt sie lediglich zu protokollieren.
  • Wenn wir unsere Rabatttools weiterentwickelt hätten, hätten wir auch selbst eine API schreiben können. Von dort aus könnten wir sogar eine Benutzeroberfläche erstellen, die mit unserer API interagiert, wenn wir wollten. Wie auch immer, ich hoffe, Sie haben jetzt die Idee! :)

Was ist der nächste Schritt? Wie fast alles auf dem Gebiet der Entwicklung müssen Sie noch mehr Code, Code, Code und Code erstellen! So machen Sie sich mit der API-Verwaltung und -Integration vertraut.

Nach einer Weile werden Sie mit ihnen effizienter.

Und hier beginnt der wahre Spaß.

Wenn Ihnen dieser Beitrag gefallen hat, nehmen Sie sich bitte eine Sekunde Zeit, um ihn auf Twitter zu klatschen und zu teilen. Haben Sie Kommentare, Fragen? Schlagen Sie den Abschnitt unten!

Ich habe dies ursprünglich im Snipcart-Blog veröffentlicht und in unserem Newsletter geteilt.