Endpunktbenennung
Mit Frends API können Sie die Best Practices von Rest-APIs befolgen, wenn es um die Benennung der Endpunkte geht. Wie bei Restful sollten HTTP-Methoden nicht in den Endpunkten verwendet werden. Zum Beispiel/api/beispiel/getbooks
kann bereits mit der Get-Methode definiert werden, sodass es nicht notwendig ist, im Namen zu definieren, wofür der Endpunkt ist. Die Get-Methode erledigt das bereits. Eine bessere Lösung für den Endpunkt wäre also/api/beispiel/bücher
.
Bei der Entwicklung von API-Endpunkten sollten Sie immer Plural-Namenskonventionen bevorzugen, z. B./Bücher
anstatt/Buch
. Dadurch wird es für Endbenutzer und Entwickler verständlicher. Normalerweise holen Sie ein einzelnes Buch aus einer Liste/einem Katalog von Büchern, daher ist dies eine eher definierende Namenskonvention.
Durch die Verschachtelung von Ressourcen können Sie Ihre APIs effizienter und benutzerfreundlicher gestalten. Zum Beispiel/Bücher/Herr der Ringe/Teile/Die Gefährten
kann den Aufwand zum Abrufen der Ressource minimieren, wenn die Filterung bereits auf Endpunktebene erfolgt.
Eine der wertvollsten Best Practices besteht darin, Ihre Endpunkte einfach lesbar und benutzerfreundlich zu gestalten. Dies wird die Endbenutzer, Integrationsentwickler und Systemanalytiker zufriedener machen und die Entwicklung effizienter und einfacher gestalten.
Pfadversionsnummer
Bei der Entwicklung von APIs betrifft eine bewährte Vorgehensweise die Versionierung der API. In der API-Spezifikation können Sie die Versionsnummer der API in einem eigenen Eigenschaftenfeld festlegen und Frends erhöht die Buildnummer automatisch, wenn einer Agentengruppe eine neue Version bereitgestellt wird.
Normalerweise enthält die Basis-URL der API jedoch auch die API-Versionsnummer, z. B. /api/sample/v1. Hier sehen Sie die Versionsnummer „v1“, also Version eins. Dies zu ändern ist etwas schwieriger, da die Basis-URL nicht mehr geändert werden kann, nachdem Sie die API-Spezifikation zum ersten Mal gespeichert haben. Um diese Versionsnummer zu erhöhen, müssen Sie eine neue API-Spezifikation erstellen, den Inhalt der vorherigen Version kopieren und einfügen und die Basis-URL ändern, bevor Sie die Spezifikation speichern.
Normalerweise muss die Pfadversionsnummer nur in Situationen geändert werden, in denen sich die API drastisch ändert und einige Änderungen zum Abbruch führen. Daher muss dies normalerweise nur in bestimmten Situationen und nicht so oft durchgeführt werden.
Der nächste Artikel istEinführung in die API-Spezifikation. So verwenden Sie den Swagger Editor.
Verwandte ArtikelEinführung in das Frends-Terminologie-GlossarBest Practices zu Versionskonventionen in FrendsBest Practices zur Versionierung von APIsEinführung in die Bereitstellung von APIs und die API-VersionskontrolleEinführung in das Schreiben von API-Spezifikationen