Inhalt
- Mach deine Hausaufgaben
- Seien Sie konsequent
- Verwenden Sie OAuth
- Früh anfangen
- Gute Dokumentation schreiben
- API-Entwicklung: Halten Sie es einfach
Wegbringen:
Softwareentwickler möchten eine Möglichkeit, ihre Software in Ihre zu integrieren - und sie möchten nicht, dass die Dinge für sie aufgeschlüsselt werden. Hier kommt eine API ins Spiel.
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 Pannen für sie. 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. In diesem Artikel möchte ich fünf Schritte hervorheben, 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 sich nicht sicher sind, welche API-Schnittstelle Sie verwenden werden, würde ich vorschlagen, einen REST-Ansatz unter Verwendung des HTTP-Protokolls zu wählen. Es ist einfacher als SOAP, das derzeit beliebter ist, und der Einstieg in ein webbasiertes Softwareprodukt ist einfacher.
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 Zusammenhang mit dem von Ihnen ausgeführten API-Aufruf einen Sinn ergeben. Stellen Sie für die Ausgabe sicher, dass Sie allgemeine Datenstrukturlayouts verwenden. Wenn Sie die Ausgabe eines API-Aufrufs in ein
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 für Ihren Server sammelt. 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 Benutzeroberfläche 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, möchten die meisten dies nicht.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.