Die Beste Blockchain API Design Vorgehensweise!

Die Beste Blockchain API Design Vorgehensweise!


Zurück zu Neu beim Nirolution Blockchain API Tutorial Blog

Die Beste Blockchain API Design Vorgehensweise!

Eine gute Blockchain API zu entwickeln ist nicht einfach. Dabei sind eine gute API Strategie und ein gutes API Design entscheidend für den Erfolg am Markt. Nachdem wir analysiert haben, wie eine gute Blockchain API aussieht, zeige ich dir nun die beste Vorgehensweise für ein gutes und erfolgreiches API Design.

„Die Beste Blockchain API Design Vorgehensweise!“ – Content:

  1. Beste Vorgehensweise für URIs
  2. Beste Vorgehensweise für Versioning
  3. Die Beste Vorgehensweise bei Error Handling
  4. Beste Vorgehensweise: Coding
  5. „API Design Vorgehensweise“ – Zusammenfassung

Beste Vorgehensweise für URIs

Ein wichtiges Element bei der Entwicklung einer Blockchain API ist der Uniform Ressource Identifier. Es ist ein Identifikator und besteht aus einer Zeichenfolge, die zur Identifizierung einer abstrakten oder physischen Ressource dient. Gerade im Internet und auch für APIs ist er fast nicht mehr wegzudenken. Doch wie sollte die URI für unsere Blockchain API gestaltet sein?

Jedoch nicht zu verwechseln mit einer URL, kurz für Uniform Ressource Locator. Eine URI kann zum Beispiel ein Name für eine Online Ressource sein, wohingegen eine URL lediglich den Standort verrät. Ohne weiter genauer ins Detail zu gehen, ist der Hauptunterschied an einem Beispiel schnell erklärt. Dein Name könnte eine URI sein, weil es genau dich identifiziert, wohingegen das Wissen über deinen Namen (URL) niemanden hilft, deinen derzeitigen Standort zu finden.)

Zunächst einmal sollte die URI kurz und einfach zu lesen sein. Das hört sich einfach an, nimmt aber doch mehr Zeit in Anspruch als man denkt.
Zudem ist es wichtig einheitliche Namen, Cases und Pattern zu benutzen.
In der URI sollten immer plurale Nomen verwendet werden und strikt Lowercase oder CamelCase benutzt werden. Das heißt wir arbeiten nur mit kleingeschriebenen Namen.

Also Verbindungsstücke zwischen Wörtern solle ein Bindestrich genommen werden.

Zudem solltest du bei der URI nur Schrägstriche benutzten, wo es Sinn macht. Die URI sollte hierbei niemals mit einem Schrägstrich enden.

Schlecht: Bücher/21/Kapitel/2/
Gut: Bücher/21/Kapitel/2

Das URI Design sollte hierarchisch sein, da sie die effektivste Form darstellt. Bei einer 1 zu n Beziehung kann die URI folgendermaßen aufgebaut werden:

:collection/:item/:sub-collection/:sub-item

Ein Beispiel in der Praxis sähe folgendermaßen aus:

/Gruppe/Gruppe1/Personen/Person1

Bei einer n zu m Beziehung kannst du dieselbe Vorgehensweise benutzten. Jedoch haben wir hierbei zwei Probleme. Was ist mit Caching?
Wenn ich etwas in meinem Backend ändere, passiert jedoch nichts in der Caching Ebene.
Zudem ist es unklar, welche URI Abfrage zuerst upgedated werde soll.
Also was können wir tun, um das Problem zu lösen?
Wir fügen zusätzliche Objekte ein. In unserem Beispiel kommen zu den Gruppen und den Personen ein Objekt namens Mitgliedschaft hinzu.

Membership beinhaltet in unserem Beispiel die GruppeID und die PersonenID. Dadurch können wir ganz einfach auf die Informationen zugreifen oder die Person löschen.

Beste Vorgehensweise für Versioning

Eine API kann sich über die Zeit verändern. Hierbei können sich die Daten oder die Sprache verändern. Beim Daten Versioning ist es wichtig, dass die Bedeutung immer dieselbe sein sollte. Das ist wichtig, um den API Konsumenten nicht zu verwirren.

Bei der Sprachversioning verändert oder erweitert sich die Sprache der API. Hierbei bleibt der Zustand derselbe, jedoch wird er auf eine andere Art und Weise präsentiert. Wichtig ist es bei einer Sprachänderung, dass sie vorwärts- und rückwärtskompatible ist.
Um Rückwärtskompatibilität zu gewährleisten ist es entscheidend, auf der Kundenseite einen Version Identifier zu benutzten. Auf der Server Seite sollte der neue Server beide Sprachen beherrschen.

Für die Vorwärtskompatibilität ist es wichtig, wie der Version identifier konzeptioniert wird. Denn der Client kann den Version identifier unterschiedlich interpretieren. Dafür sind unterschiedliche Algorithmen möglich. Zum Beispiel kann ein Version identifier bedeuten, dass es die neuste Version ist, die der Server unterstützt oder es beinhaltet die minimalen Anforderungen, um alle angeforderten Features ausführen.

Beste Vorgehensweise bei Error Handling

Error Handing ist ein wichtiger Faktor für eine gute Blockchain API. Denn aus Sicht des Kunden stellt die API eine Art black box dar. Wenn also irgendetwas falsch läuft und es gibt keine hilfreiche Fehlermeldung, dann weiß unser Client nicht was er tun soll. Schlussendlich sorgt dieser Zustand dazu, dass viel Zeit verschwendet wird und Frustration entsteht. Im schlimmsten Fall wird er zu einem anderen API Anbieter wechseln, was nicht nur zu Umsatzrückgängen, sondern auch zu Imageschäden führen kann.

Die gängigsten Fehlermeldungen sind Error tunneling durch 200 <<ok>> oder es wird für jedes Problem der 500 <<internal server error>> verwendet. Beide Lösungen sind nicht hilfreich und sollten auch nicht verwendet werden, da diese viel zu allgemein gehalten sind. Dem Client sollte also gesagt werden, worin das Problem bestand, damit er die Möglichkeit hat das Problem zu lösen. Dies sind die gängigsten Fehlermeldungen:
<<400 <bad request>>
<<404 <not found>>
<<403 <forbidden>>
<<500 <internal server error>>
<<503 <service unavailable>>
<<504 <gateway timeout>>
Die beste Methode, um mit Fehlermeldungen umzugehen ist es, dem Entwickler deutlich mitzuteilen, was passiert ist. Es könnte Folgenderweise aussehen:

{
 “errors“ : [ 
    {
    “message“ : “Sorry, that page does not exsist“,
    “code“ : 34
    “more_infor“: “http://www.help.com/errors“
    }
 ]
}

Dadurch weiß der Benutzer sofort, was falsch gelaufen ist und kann dementsprechend reagieren. Es sollte auch einen Link geben, um eine Erklärung zu jeder Fehlermeldung geben zu können.

Beste Vorgehensweise: Coding

Des Weiteren solltest du folgende Programmierempfehlungen berücksichtigen:

  • Es sollte so wenig wie möglich veränderbar sein
  • Unterklasse nur dort, wo es sinnvoll ist
  • Benutze Vererbungen oder verbiete es
    • Lasse den Client nicht alles tun, was ein Modul tun könnte
  • Vorsicht mit Überlastungen
  • Verwende geeignete Parameter- und Rückgabetypen
    • Für Eingaben ist ein Interface besser als eine Klasse
    • Benutzte möglichst spezifische Eingabeparametertypen
    • Verwende keine Zeichenkette, wenn ein besserer Typ vorhanden ist
    • Benutze kein Fließkomma für Geldwerte
    • Verwende Double anstelle von Float, da diese viel genauer sind sprich mehr Nachkommastellen
  • Konsistente Parameteranordnung über alle Methoden hinweg verwenden
  • Lange Parameterlisten vermeiden
  • Benutze Exceptions, um auf außergewöhnliche Bedingungen hinzuweisen
  • Verstoße nicht gegen das principle of least astonishment (Prinzip der geringsten Überraschung)
  • Behebe Fehler, sobald sie auftreten
  • Stelle jeden programmatischer Zugriff auf alle Daten in Zeichenkettenform bereit

„API Design Vorgehensweise“ – Zusammenfassung

Unsere Blockchain API Design Vorgehensweise zeigt dir, welche Schritte für ein tolles API Design wichtig sind. Hierbei ist es entscheidend, dass die URI kurz und einfach zu lesen ist. Zudem solltest du Konstant mit Namen etc. sein und immer plurale Nomen verwenden. Dabei immer lowercase/camelcase, hypen benutzten und dabei die URI hierarchisch aufbauen. Beim Daten Versioning ist es wichtig, dass die Daten geändert werden aber die Bedeutung immer dieselbe sein sollte. Beim Sprach Versioning ist es wichtig, dass der Zustand derselbe sein sollte, aber die Daten anders dargestellt werden. Hierbei ist es entscheidet, dass es sowohl Vorwärts- als auch Rückwärtskompatibel sein muss. Bei Fehlermeldungen ist es zwingend notSoliman Michael wendig dem Entwickler mitzuteilen, was falsch gelaufen ist. Eine aussagekräftige Fehlermeldung und ein Link zur Interpretation des Problems sind erfolgsentscheidend.
Wenn du diese API Design Vorgehensweise einhältst und unsere Programmierratschläge befolgst, kann deine Blockchain API nur ein Erfolg werden.

Wenn du über die neusten Artikel informiert werden möchtest, folge uns auf Facebook, Pinterest and Steemit.

Bleibe bei deinen Lieblingsthemen auf dem laufenden

Schreibe einen Kommentar

Menü schließen