5 Schritte zum Erstellen einer erfolgreichen API

Es liegt in der Natur der Softwareentwicklung. Entwickler entwickeln Software für den Endbenutzer. Es scheint ziemlich einfach zu sein, aber manchmal sind diese Benutzer auch Mitentwickler. Sie brauchen keine Dinge für sie aufgeschlüsselt. Sie brauchen nicht einmal die Einfachheit. Alles, was sie wollen, ist Zugriff - eine Möglichkeit, Ihre Software in ihre zu integrieren. Hier kommt eine API (Application Programming Interface) ins Spiel. Ich hoffe, fünf Schritte hervorzuheben, die Sie ausführen können, um eine erfolgreiche API zu erstellen.

Mach deine Hausaufgaben

Wenn es um Softwareentwicklung geht, möchte keiner von uns das Rad neu erfinden. Zu diesem Zeitpunkt verfügen fast alle großen Webunternehmen über APIs für ihre Softwareprodukte. Studieren Sie diese APIs und versuchen Sie, die verschiedenen Entwurfsentscheidungen aufzugreifen, mit denen sie erstellt wurden.

Es gibt viele verschiedene Technologien, aber die meisten der APIs, die Sie sehen werden, werden entweder eine RESTful-Schnittstelle oder SOAP verwenden. Wenn Sie wissen, welche API-Schnittstelle Sie verwenden möchten, würde ich einen REST-Ansatz unter Verwendung des HTTP-Protokolls vorschlagen. Es ist einfacher als SOAP, es ist derzeit beliebter und es ist einfacher, mit der Verwendung eines webbasierten Softwareprodukts zu beginnen.

Seien Sie konsequent

Eines der Dinge, die Entwickler am meisten schätzen, ist die Konsistenz. Dies beinhaltet unter anderem Adressierbarkeit, Eingabeargumente, Ausgabeformate und Fehlerbehandlung.

Bei Verwendung eines RESTful-Ansatzes gibt es viele verschiedene URI-Benennungsschemata. Jeder hat seine Anhänger, also wählen Sie einfach einen aus und bleiben Sie dabei. Gleiches gilt für die Eingabe- und Ausgabestruktur. Die meisten APIs unterstützen die Verwendung von XML und JSON als Eingabe- und Ausgabeformate. Ich würde vorschlagen, beide zu unterstützen, aber ein Standardformat zu wählen.

Für die Eingabe sollten Ihre Eingabeanforderungen konsistent benannt sein und im Kontext des von Ihnen ausgeführten API-Aufrufs einen Sinn ergeben. Stellen Sie für die Ausgabe sicher, dass Sie allgemeine Datenstrukturlayouts verwenden. Wenn Sie die Ausgabe eines API-Aufrufs in ein XML-Tag, überlegen Sie, ob Sie dies mit Ihren anderen Aufrufen tun möchten.

Es ist üblich, eine Art Status-Flag in die Ausgabedaten aufzunehmen, die Sie an den Client zurücksenden. Bei Verwendung eines RESTful-API-Ansatzes sollte dies unter Verwendung von HTTP-Statuscodes erfolgen. Wenn Sie beispielsweise gerade eine PUT-Anforderung für ein vorhandenes Datenobjekt verarbeitet haben, hängt der in Ihrer Antwort enthaltene HTTP-Statuscode vom Ergebnis der Anforderung ab.

Anstelle eines beliebigen Flags, das den Status des Anrufs angibt, kann ein Standardstatuscode "200 OK" verwendet werden, um anzuzeigen, dass die Anforderung erfolgreich war, während ein Statuscode "400 Bad Request" verwendet werden kann, um anzuzeigen, dass die Anforderung erfolgreich war missgebildet. Es gibt einige HTTP-Statuscodes, die in verschiedenen Situationen verwendet werden können.

Verwenden Sie OAuth

Die meisten Softwareprodukte erfordern eine Art Benutzerauthentifizierung, um auf geschützte Ressourcen für diesen Benutzer zuzugreifen. Wenn es um APIs geht, ist es eine schlechte Praxis, wenn der Client die Benutzeranmeldeinformationen sammelt, die an Ihren Server gesendet werden sollen. Hier kommt OAuth ins Spiel.

OAuth bietet viele Vorteile gegenüber der Authentifizierung mit Benutzernamen / Passwort von Drittanbietern. Vor allem hat der Client nie Zugriff auf die Anmeldeinformationen des Benutzers. Der Benutzer wird bei der Anmeldung auf Ihren Server umgeleitet. Nachdem sich der Benutzer bei Ihrer Site angemeldet hat, wird er an den Client zurückgeleitet, auf dem der Client ein Zugriffstoken erhält, das für zukünftige Anforderungen an geschützte Ressourcen verwendet werden kann.

Ein weiterer wichtiger Vorteil der Verwendung von OAuth ist die Möglichkeit des Benutzers, den Clientzugriff jederzeit zu kündigen. Wenn der Benutzer feststellt, dass der Client aus irgendeinem Grund nicht mehr in der Lage sein soll, in seinem Namen auf geschützte Ressourcen zuzugreifen, wird einfach eine von Ihnen erstellte Schnittstelle aufgerufen und der Clientzugriff abgebrochen.

Früh anfangen

Eines der wichtigsten Dinge, die Sie tun können, um Ihre API zum Erfolg zu führen, ist ein früher Start. Wenn Sie diese Funktion schreiben, um einen Eintrag in Ihrer Datenbank zu erstellen, nehmen Sie sich die zusätzliche Zeit und schreiben Sie eine API-Schnittstelle dafür.

Gute Dokumentation schreiben

Nichts bringt eine API schneller zum Erliegen, als keine gute Dokumentation zu haben. Während einige Entwickler eine schlecht dokumentierte API verwenden und herausfinden können, wie sie funktionieren soll, werden die meisten dies nicht wollen.

Sie sollten jeden verfügbaren API-Aufruf dokumentieren und Ihre API-Aufrufe nach dem Datentyp kategorisieren, auf den sie sich beziehen. Neben der Dokumentation der Endpunkte für die API-Aufrufe selbst sollten Sie die erforderlichen und optionalen Eingabeargumente sowie die Ausgabedatenstrukturen systematisch definieren. Eingabeargumente sollten einen Standardwert auflisten, sofern vorhanden, und auch das erwartete Datenformat angeben, z. B. eine Zahl oder eine Zeichenfolge. Schließlich sollte jeder API-Aufruf eine Liste mit Fehlerbedingungen und Statuscodes enthalten.

Um Ihre Dokumentation abzurunden, sollten Sie für jeden API-Aufruf ein oder zwei Beispiele für allgemeine Eingabe- und Ausgabeszenarien angeben.

API-Entwicklung: Halten Sie es einfach

Die Entwicklung einer API scheint zwar ein kompliziertes Unterfangen zu sein, die Idee einer API selbst ist jedoch kein neues Konzept, und zu jedem Thema, das wir hier angesprochen haben, steht eine große Menge an Dokumentation zur Verfügung. Stellen Sie nur sicher, dass Sie bewährte Methoden verwenden, wo Sie sie finden können, und dass Sie eine konsistente, gut dokumentierte Oberfläche bereitstellen.