Die besten Best Practices für die REST-API

Blog

Die besten Best Practices für die REST-API

In diesem Beitrag wird es mein Ziel sein, REST so klar wie möglich zu erklären, damit Sie klar verstehen, wann und wie es verwendet wird und was es im Wesentlichen ist.



Viele Giganten wie Facebook, Google, GitHub, Netflix, Amazon und Twitter haben ihre eigenen REST(ful) APIs, auf die Sie zugreifen können, um Daten abzurufen oder sogar zu schreiben.

Aber warum all die Notwendigkeit für REST?



Ist es so gut und warum ist es so verbreitet?

Sicherlich ist es nicht die einzige Möglichkeit, Botschaften zu übermitteln?



Was ist der Unterschied zwischen REST und HTTP?

Nun, es stellt sich heraus REST ist ziemlich flexibel und kompatibel mit HTTP (das ist das Hauptprotokoll, auf dem das Internet basiert). Da es sich um einen architektonischen Stil und nicht um den Standard handelt, ist es bietet viel Freiheit bei der Implementierung verschiedener Best Practices für das Design . Habe ich schon erwähnt, dass es sprachunabhängig ist?

In diesem Blogbeitrag wird es mein Ziel sein, REST so klar wie möglich zu erklären, damit Sie klar verstehen, wann und wie es verwendet wird und was es im Wesentlichen ist.

Wir werden einige Grundlagen und Definitionen durchgehen und einige zeigen Best Practices für die REST-API . Dies sollte Ihnen alle Kenntnisse vermitteln, die Sie benötigen, um REST-APIs in jeder Sprache zu implementieren, in der Sie lieber codieren.

Wenn Sie mit HTTP nicht so vertraut sind, empfehle ich Ihnen, unsere HTTP-Serie , oder zumindest Teil 1 davon, damit Sie dieses Material leichter verdauen können.

Was ist also REST im Wesentlichen?

REST (Representational State Transfer) ist ein Architekturstil, der von Roy Fielding in seinem Ph.D. Dissertation Architekturstile und der Entwurf netzwerkbasierter Softwarearchitekturen an der UC Irvine. Er hat es parallel zu HTTP 1.1 (kein Druck) entwickelt.

Wir verwenden REST in erster Linie als Möglichkeit zur Kommunikation zwischen Computersystemen im World Wide Web .

Ist REST an HTTP gebunden?

Per Definition ist es das nicht. Obwohl Sie mit REST ein anderes Anwendungsprotokoll verwenden können, HTTP ist der unangefochtene Champion unter den Anwendungsprotokollen geblieben, wenn es um die Implementierung von REST geht.

REST- und HATEOAS-Unterstützung

HATEOAS oder **Hypermedia As The Engine Of Application State ** ist das wichtige Merkmal jeder skalierbaren und flexiblen REST-API.

Die HATEOAS Constraint schlägt vor, dass Client und Server vollständig unter Verwendung der Hypermedien .

Die Verwendung von Hypermedia hat mehrere Vorteile:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden

Es ist also klar, dass der HATEOAS war auf Langlebigkeit ausgelegt .

So macht es GitHub:

GET https://api.github.com/users/codemazeblog

Antwort:

{ 'login': 'CodeMazeBlog', 'id': 29179238, 'avatar_url': 'https://avatars0.githubusercontent.com/u/29179238?v=4', 'gravatar_id': '', 'url': 'https://api.github.com/users/CodeMazeBlog', 'html_url': 'https://github.com/CodeMazeBlog', 'followers_url': 'https://api.github.com/users/CodeMazeBlog/followers', 'following_url': 'https://api.github.com/users/CodeMazeBlog/following{/other_user}', 'gists_url': 'https://api.github.com/users/CodeMazeBlog/gists{/gist_id}', 'starred_url': 'https://api.github.com/users/CodeMazeBlog/starred{/owner}{/repo}', 'subscriptions_url': 'https://api.github.com/users/CodeMazeBlog/subscriptions', 'organizations_url': 'https://api.github.com/users/CodeMazeBlog/orgs', 'repos_url': 'https://api.github.com/users/CodeMazeBlog/repos', 'events_url': 'https://api.github.com/users/CodeMazeBlog/events{/privacy}', 'received_events_url': 'https://api.github.com/users/CodeMazeBlog/received_events', 'type': 'User', 'site_admin': false, 'name': 'Code Maze', 'company': 'Code Maze', 'blog': 'https://code-maze.com', 'bio': 'A practical programmers' resource.', ... }

Wie Sie sehen, finden Sie neben den vom Kunden angeforderten wichtigen Informationen in der Antwort eine Reihe verwandter Hypermedia-Links, die Sie zu anderen Teilen der API führen, die Sie frei erkunden können.

Was bedeutet RESTful-API?

RESTful impliziert einige Funktionen:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden

Die RESTful API ist also ein Dienst, der diese Regeln (hoffentlich) befolgt und verwendet HTTP-Methoden um die Ressourcenmenge zu manipulieren.

Aber warum brauchen oder verwenden wir RESTful APIs?

Weil sie uns eine einfache, flexible und skalierbare Möglichkeit bieten, verteilte Anwendungen zu erstellen, die über das Internet kommunizieren.

Können wir zu viel RUHE haben?

Ja, Sie haben es erraten. Ja wir können.

Es gibt sogar einen Satz für die Leute, die REST fanatisch verfolgen, wie definiert von Mike Schinkel.

ZU RESTifarian ist ein eifriger Befürworter des REST Softwarearchitekturstil wie definiert durch Roy T. Fielding in Kapitel 5 von seinem Ph.D. Dissertation bei UCIrvine . RESTifarians in freier Wildbahn findet ihr auf der REST-Mailingliste diskutieren . Aber seien Sie vorsichtig, RESTifarianer können äußerst akribisch sein, wenn sie die Feinheiten von REST besprechen, da Ich habe vor kurzem gelernt während der Teilnahme an der Liste.
Zu viel von allem kann schlecht sein.

Wir brauchen ein bisschen Pragmatismus um gute Anwendungen und Dienste zu erstellen. Es ist wichtig, eine Theorie zu kennen und zu verstehen, aber die Umsetzung dieser Theorie ist es, die schlechte von guten und exzellenten Anwendungen unterscheidet. Seien Sie also schlau, denken Sie an den Endbenutzer.

Schauen wir uns also einige wichtige Punkte an, die APIs glänzen und das Leben der Benutzer viel einfacher machen.

Abstrakte vs. konkrete APIs

Bei der Entwicklung von Software verwenden wir oft Abstraktion und Polymorphismus, um die meisten unserer Anwendungen zu erhalten. Wir möchten so viel Code wie möglich wiederverwenden.

Sollten wir unsere APIs also auch so schreiben?

Nun, das ist bei APIs nicht genau der Fall. Für REST-APIs, konkret ist besser als abstrakt . Kannst du erraten warum?

Lassen Sie mich Ihnen ein paar Beispiele zeigen.

Schauen wir uns zwei API-Versionen an. Ist es besser, eine API mit einer |_+_| . zu haben? oder eine API mit |_+_|, |_+_| und, |_+_|getrennt?

Welches erscheint Ihnen als Entwickler aussagekräftiger? Welche API würden Sie lieber verwenden?

Ich würde immer den zweiten wählen.

URI-Formatierung (Substantive, keine Verben): Beispiele für gute URLs vs. schlechte URLs

Hier ist eine weitere Best Practice für die REST-API. Wie sollten Sie Ihre Endpunkte formatieren?

Wenn Sie den Softwareentwicklungsansatz verwenden, erhalten Sie so etwas:

/getAllBlogPosts

/updateBlogPost/12

/deleteBlogPost/12

/getAuthorById/3

/deleteAutor/3

/updateAutor/3

Sie verstehen, worauf es ankommt… Es wird eine Menge Endpunkte geben, von denen jeder etwas anderes macht. Es gibt ein besseres System, um dieses Chaos auszusortieren.

Behandeln Sie die Ressource wie ein Nomen und die HTTP-Methode wie ein Verb. Wenn Sie es so machen, erhalten Sie so etwas:

|_+_| - bekommt alle Blog-Beiträge.

|_+_| - bekommt den Blogbeitrag mit der ID 12.

|_+_| - fügt einen neuen Blogbeitrag hinzu und gibt die Details zurück.

|_+_| - entfernt den Blog-Beitrag mit der ID 12.

|_+_| - bekommt alle Blogbeiträge des Autors mit der ID 3.

Dies ist eine sauberere und präzisere Möglichkeit, die API zu verwenden. Für den Endverbraucher ist es sofort klar, und der Wahnsinn hat Methode.

Sie können es noch übersichtlicher machen, indem Sie für die Ressourcennamen Singular anstelle von Plural verwenden. Das liegt an dir.

Fehlerbehandlung

Dies ist ein weiterer wichtiger Aspekt der API-Erstellung. Es gibt einige gute Möglichkeiten, mit Fehlern umzugehen.

Mal sehen, wie es die Platzhirsche machen.

Twitter:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden
/entities

Twitter gibt Ihnen den Statuscode und den Fehlercode mit einer kurzen Beschreibung der Art des aufgetretenen Fehlers. Sie überlassen es Ihnen, die Codes auf ihrer Seite nachzuschlagen Antwortcodes Seite.

Facebook:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden
/owners

Facebook gibt Ihnen eine aussagekräftigere Fehlermeldung.

Twilio:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden
/blogs

Twilio gibt Ihnen standardmäßig eine XML-Antwort und den Link zur Dokumentation, in der Sie die Fehlerdetails finden.

Wie Sie sehen, unterscheiden sich die Ansätze zur Fehlerbehandlung von Implementierung zu Implementierung.

Wichtig ist den Benutzer der REST-API nicht hängen zu lassen, d.h. nicht zu wissen was passiert ist oder ziellos durch die Abfälle von StackOverflow wandern und nach der Erklärung suchen.

Statuscodes

Beim Entwerfen einer REST-API kommunizieren Sie mit dem API-Benutzer, indem Sie HTTP-Statuscodes . Es gibt viele Statuscodes, die mehrere mögliche Antworten beschreiben.

Aber wie viele sollten Sie verwenden? Sollten Sie für jede Situation einen strengen Statuscode haben?

Wie bei vielen Dingen im Leben ist die KISS-Prinzip gilt auch hier. Es gibt über 70 Statuscodes. Kennst du sie auswendig? Wird der potenzielle API-Benutzer sie alle kennen oder wird es wieder zu googelnem Zeug führen?

Die meisten Entwickler kennen die gängigsten Statuscodes:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden

Wenn Sie mit diesen drei beginnen, können Sie die meisten Funktionen Ihrer REST-API abdecken.

Andere häufig verwendete Codes sind:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden

Sie können diese verwenden, um dem Benutzer zu helfen, schnell herauszufinden, was das Ergebnis war. Sie sollten wahrscheinlich eine Art Nachricht einfügen, wenn Sie der Meinung sind, dass der Statuscode nicht aussagekräftig genug ist, wie wir im Abschnitt zur Fehlerbehandlung besprochen haben. Seien Sie noch einmal pragmatisch, helfen Sie dem Benutzer, indem Sie a begrenzte Anzahl von Codes und beschreibende Nachrichten.

Sie finden die vollständige Liste der HTTP-Statuscodes sowie andere hilfreiche HTTP-Sachen Hier .

Sicherheit

Zur REST API-Sicherheit gibt es nicht viel zu sagen, denn REST beschäftigt sich nicht mit Sicherheit . Es basiert auf Standard-HTTP-Mechanismen wie Basic- oder Digest-Authentifizierung .

Jede Anfrage sollte gestellt werden über HTTPS .

Es gibt viele Tricks, um die Sicherheit Ihrer REST-API zu verbessern, aber Sie müssen bei der Implementierung vorsichtig sein, da REST zustandslos ist. Das Erinnern des Status der letzten Anfrage geht aus dem Fenster, und die Client ist der Ort, an dem der Status gespeichert und überprüft werden soll.

Zeitstempelung und Protokollierung Anfragen können auch ein wenig helfen.

Firefox öffnet Google Mail nicht

Zu diesem Thema gibt es noch viel mehr zu sagen, aber es würde den Rahmen dieses Beitrags sprengen. Wir haben einen schönen Beitrag auf HTTP-Sicherheit wenn Sie mehr darüber erfahren möchten.

REST API-Versionierung

Sie haben Ihre REST-API bereits geschrieben und sie war sehr erfolgreich und viele Leute haben sie verwendet und sind damit zufrieden. Aber Sie haben diese saftige neue Funktionalität, die andere Teile des Systems zerstört. Die brechende Veränderung.

Keine Angst, dafür gibt es eine Lösung!

Bevor Sie mit der Erstellung Ihrer API beginnen, können Sie Ihre API versionieren, indem Sie den Endpunkten die API-Version voranstellen: https://api.example.com/v1/authors/2/blogposts/13

Auf diese Weise können Sie Ihre API-Versionsnummer (z. B. v2, v3…) immer erhöhen, wenn es an Ihrer API bahnbrechende Änderungen gibt. Dies signalisiert den Benutzern auch, dass sich etwas drastisch geändert hat und sie bei der Verwendung der neuen Version vorsichtig sein sollten.

Bedeutung der Dokumentation

Dieser ist ein Kinderspiel. Sie könnten der beste API-Designer der Welt sein, aber Ohne Dokumentation ist Ihre API so gut wie tot.

Eine ordnungsgemäße Dokumentation ist unerlässlich für jedes Softwareprodukt und jeden Webservice gleichermaßen.

Sie können dem Benutzer helfen, indem Sie konsistent sind und eine klare und beschreibende Syntax verwenden. Aber es gibt keinen wirklichen Ersatz für gute alte Dokumentationsseiten.

Hier sind einige der großartigen Beispiele:

  • Es ermöglicht API-Designern, anstatt alles, was sie können, in jede Antwort aufzunehmen, eine Sache richtig und Hypermedia-Links zu verwandten Endpunkten bereitzustellen und so das Design zu entkoppeln
  • Es hilft der API, sich eleganter zu entwickeln und zu reifen
  • Es bietet dem Benutzer die Möglichkeit, die API tiefer zu erkunden

Es gibt viele Tools, mit denen Sie Ihre API dokumentieren können, aber vergessen Sie nicht, den menschlichen Touch hinzuzufügen, denn nur ein Mensch kann einen anderen richtig verstehen. Zumindest für den Moment (wenn man sich deine KI ansieht).

Abschluss

Wir haben viele Konzepte des REST-API-Gebäudes durchgearbeitet und einige der besten REST-API-Best Practices behandelt. Diese mögen bei der sofortigen Bereitstellung etwas seltsam oder überwältigend erscheinen, aber versuchen Sie, Ihre eigene REST-API zu erstellen. Und versuchen Sie, einige der bewährten Methoden für die REST-API zu implementieren, die Sie hier gelernt haben.

Machen Sie die kleinste API, die möglich ist, und sehen Sie, wie sie aussieht. Sie werden überrascht sein, wie gut es ausgehen kann, wenn Sie nur diese wenigen Praktiken befolgen.

#rest #api #web-entwicklung