Wie soll ich eine gute (Web-) API erstellen?

Question

Ich werde eine API für eine Web-App erstellen und mich dafür interessieren, was die Leute als gute Praktiken vorschlagen können.

Ich plane bereits, es versionsfähig zu machen (Version 1 kann nur bestimmte Aspekte des Systems kontrollieren, Version 2 könnte mehr kontrollieren, aber dies könnte eine Änderung der Art der Authentifizierung erfordern, die mit Version 1 inkompatibel wäre), und die Authentifizierung unterscheidet sich von dem Standardbenutzernamen/Passwort, mit dem sich Benutzer einloggen (wenn jemand ein böswilliges Tool verwendet, wird es sie nicht für den vollständigen Identitätswechsel öffnen, egal was die API erlaubt).

Hat jemand weitere Ideen oder Beispiele für Websites mit besonders guten APIs, die Sie verwendet haben?

Answer 1

Lesen Sie das Buch RESTful Web Services, in dem Sie einen guten Überblick darüber erhalten, wie Sie REST in der Praxis einsetzen und schnell genug auf den neuesten Stand bringen, um mit einiger Sicherheit zu beginnen. Dies ist nützlicher, als nur eine vorhandene API zu betrachten, da auch Designentscheidungen und Trade-Offs diskutiert werden.

Answer 2

Verwenden Sie REST.

RESTful Web Services Architektur ist einfach zu implementieren und nutzt die Stärken und Semantiken von HTTP für das, was sie beabsichtigt waren. Es ist ressourcenorientiert, genau wie das Web selbst.

Amazon Web Services, Google und viele andere bieten REST-APIs zur Interaktion mit ihren Produkten an.

Answer 3

ich einen Blick auf bewährte APIs nehmen würde:

1. YouTube API
2. Twitter API

Es gibt eine Menge Argument darüber, ob diese APIs sind "gut", aber ich denke, ihr Erfolg demonstriert und sie sind alle einfach zu benutzen.

Answer 4

Verwenden Sie REST.

Lesen Sie sich über Standards für APIs, oder kopieren Sie die Ideen von einem der beliebtesten.

Seien Sie vorsichtig, wenn Sie Benutzer authentifizieren.

Start sehr sehr einfach.

Erstellen Sie eine Website, die Ihre API verwendet (auch wenn es nicht sinnvoll ist), um die Arbeit zu überprüfen. Vielleicht könnten Sie eine mobile Version der Website erstellen oder etwas, das Sie dazu zwingt, die API in großer Tiefe zu verwenden.

Answer 5

1) Bake die Versionsnummer direkt in die URL, anstatt sie als Parameter zu übergeben, da Sie damit die Freiheit haben, die Organisation Ihres API-Namespace mit jedem Versions-Bump zu ändern.

2) Halten Sie Ihre URL-Rewriter-Regeln (falls vorhanden) so einfach/schlank wie möglich (aber nicht einfacher), während Sie Ihre URLs so schön wie möglich machen (aber nicht mehr).

3) Suchen Sie immer nach dem besten HTTP-Statuscode, den Sie für jede Antwort finden können (und vergessen Sie nicht etwa 202 und 207).

4) Implementieren Sie faschistische Parametervalidierungslogik und informative Fehlermeldungen.

5) Verwenden Sie gegebenenfalls HTTP-Anforderungsheader anstelle von Parametern (z. B. Akzeptieren, damit Clients das gewünschte Datenformat der Antwort angeben können).

6) Organisieren Sie Ihre "Substantive" so, dass die URLs, die von verschiedenen Client-Zielgruppen verwendet werden, in der Nähe des "Stamms" Ihrer URL-Struktur getrennt sind (dies erleichtert die Durchsetzung verschiedener Authentifizierungsmechanismen für diese unterschiedlichen Zielgruppen) oder sogar verschiedene Teile Ihrer URL-Struktur verschiedenen Servern zuordnen).

7) Wenn Sie reguläre Webseiten von derselben Domain wie Ihre APIs bedienen und dieselben Authentifizierungsdaten verwenden, müssen Sie in Ihren API-Anfragen einen X-Requested-With-Header eingeben, um XSRF-Sicherheitslücken zu vermeiden.