25.09.2017

  • rest
  • api
  • uri
application gear 512

Guy Levin hat auf dem Blog http://blog.restcase.com/7-rules-for-rest-api-uri-design/ eine nützliche Übersicht des URI-Designs für REST-Services zusammengestellt. Wir stellen die Information hier frei übersetzt in deutscher Sprache zur Verfügung. 

aus der Technik entwickelt im Auftrag viele Micro- und REST-Services, wir legen großen Wert auf die intuitive Benutzbarkeit unsere APIs. Der Artikel von Guy beinhaltet 7 kleine Regeln für das Design der URI, welche die Benutzbarkeit einer API erheblich verbessern. Diese Regeln möchten wir mit unseren Kunden teilen, da sie verständlich und kompakt erklärt wurden. 

Original-Quelle: Guy Levin (http://blog.restcase.com/5-basic-rest-api-design-guidelines/)


Begrifflichkeit

Bevor wir zu den Regeln für das REST-API URl-Design kommen schauen wir uns kurz die Begriffe an, die verwendet werden.

URIs

REST-APIs benutzen Uniform Resource Identifiers (URIs), um Ressourcen anzusprechen. Im heutigen Internet reicht die Bandbreite der URI Designs von Meisterstücken, die klar das Ressourcen-Modell der API widerspiegeln, wie...
http://api.example.com/louvre/leonardo-da-vinci/mona-lisa 

...bis hin zu schwer zu verstehenden Designs wie:
http://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66

Tim Berners-Lee sagt in seiner Liste „Axioms of Web Architecture“ zur Opazität von URIs: "Das Einzige, was als Identifizierungsmerkmale benutzt werden kann, ist auf ein Objekt zu verweisen. Erfolgt kein Rückverweis, sollte man den Inhalt der URI-Adresse nicht als Quelle für andere Informationen betrachten."
- Timer Berners-Lee https://www.w3.org/DesignIssues/Axioms.html

Kunden müssen die Paradigmen für Links im Web befolgen und URIs als undurchsichtige Identifikatoren behandeln.
Designer von REST-APIs sollten URIs erstellen, die das Ressourcen-Modell einer REST-API den potentiellen Entwicklern des Kunden vermitteln.
Dieser Blog-Post führt erste Design-Regeln für REST-APIs ein.

Bevor wir in die Regeln abtauchen ein Wort zum URI-Format, da die in diesem Abschnitt enthaltenen Regeln das Format eines URI betreffen.
RFC 3986 (https://www.ietf.org/rfc/rfc3986.txt) definiert die generische URI-Syntax wie unten gezeigt:
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

Regel #1: Ein nachstehender Schrägstrich sollte nicht in URIs aufgenommen werden

Dies ist eine der wichtigsten Regeln, da die letzte Ziffer in einem URI-Pfad, ein Schrägstrich, keinen semantischen Wert hinzufügt und eventuell zu Verwirrungen führt. REST-APIs sollten keinen Schrägstrich annehmen und ihn nicht in den Links enthalten, die sie Kunden bereit stellen. Des Weiteren ist der nachstehende Schrägstrich (/) ungünstig für Dokumentationen und die Fehlersuche: Betrachten wir immer eine Trennung der Parameter mit einem Schrägstrich so wird bei einem nachstehenden Schrägstrich nicht klar, ob ein Parameter fehlt (weil er z.B. null ist) oder nicht. 

Viele Web-Komponenten und Frameworks behandeln die folgenden zwei URIs gleich:

    http://api.canvas.com/shapes/ 

    http://api.canvas.com/shapes

Jedoch gilt jedes Zeichen innerhalb einer URI für die einzigartige Identität einer Ressource.
Zwei unterschiedliche URIs verweisen auf zwei unterschiedliche Ressourcen. Sind die URIs unterschiedlich so sind es auch die Ressourcen, und umgekehrt. Aus diesem Grund muss eine REST-API saubere URIs generieren und kommunizieren, und sollte jeglichen Versuchen von Kunden, einen Ressource unpräzise zu identifizieren widerstehen.

Nachsichtige APIs können Kunden auf URIs ohne einen Schrägstrich weiterleiten (sie können auch den HTTP-Statuscode „301 - Dauerhaft verschoben“ zurückgeben, welcher zum Umzug von Ressourcen verwendet wird).

Regel #2: Ein Schrägstich muss als Trenner verwendet werden, um eine hierarchische Beziehung anzuzeigen

Der Schrägstrich (/) wird im Pfadabschnitt des URI verwendet, um eine hierarchische Beziehung zwischen den Ressourcen anzuzeigen.

Beispiel:
http://api.canvas.com/shapes/polygons/quadrilaterals/squares

Ein Quadrat ist ein besonderes Viereck, das zu einer Schnittmenge von Polygonen gehört. Polygone wiederum sind Formen, die man erhält, indem in einer Zeichenebene mindestens drei verschiedene (nicht kollineare) Punkte miteinander verbunden werden. Eine Linie zwischen zwei Punkten wäre in dem Falle zwar unter /shapes einzuordnen, nicht jedoch unter /polygons.

Regel #3: Bindestriche sollten verwendet werden, um die Lesbarkeit von URIs zu verbessern

Die Verwendung von Bindestrichen (-) dient dazu, URIs besser scan- und interpretierbar zu machen, dies verbessert die Lesbarkeit von Namen in langen Pfad-Segmenten. Überall dort, wo ein Leerzeichen oder einen Unterstrich verwenden werden würde sollte an dieser Stelle einen Bindestrich Verwendung finden.

Beispiel:
http://api.example.com/blogs/eva-simon/posts/this-is-my-first-post

Regel #4: Unterstriche sollten in URIs nicht verwendet werden

Applikationen, die Text anzeigen (Browser, Editoren etc.) unterstreichen URIs oft, um einen visuellen Hinweis zu geben, dass diese anklickbar sind. Abhängig von der Schriftart der Anwendung wird der Unterstrich (_) entweder teilweise verdeckt oder oder völlig von dieser Unterstreichung versteckt.

Um diese Verwirrung zu vermeiden sollten Bindestriche statt Unterstriche verwendet werden.

Regel #5: In URIs sollten bevorzugt Kleinbuchstaben eingesetzt werden

Grundsätzlich sollten vorzugsweise Kleinbuchstaben in URI-Pfaden verwendet werden, da Großbuchstaben manchmal Probleme verursachen können. Laut RFC 3986 beachten URIs die Groß- und Kleinschreibung, mit Ausnahme von Schema- und Host-Komponenten.

Beispiel:
http://api.example.com/my-folder/my-doc
HTTP://API.EXAMPLE.COM/my-folder/my-doc 

Diese URI ist in Ordnung. Die Spezifikation des URI-Formats (RFC 3986) erachtet diese URI als identisch zu URI #1.

http://api.example.com/My-Folder/my-doc 

Diese URI ist nicht die Gleiche wie die URIs 1 und 2, was zu unnötigen Verwirrungen führen kann. Groß- und Kleinschreibung führt eine neue, nicht benötigte, Abstraktionsebene in den REST-Service ein und sollte daher vermieden werden. 

Regel #6: Dateierweiterungen sollten nicht in URIs verwendet werden

Im Web wird der Punkt (.) oft zur Trennung des Dateinamens und der Erweiterungsabschnitte einer URI verwendet. Eine REST-API sollte keine künstlichen Dateierweiterungen in URIs enthalten, um das Format der zurückgelieferten Entity anzugeben.Stattdessen sollte sich alleine auf den dafür vorgesehenen Medientyp verlassen werden können, der über den Content-Type-Header kommuniziert wird, um zu bestimmen, wie der Inhalt der Antwort formatiert werden soll. Ist dies nicht gegeben, so ist unklar welche Angabe verwendet wird und es kommt zu Konflikten und Fehlinterpretationen der API. 

http://api.college.com/students/3248234/courses/2005/fall.json 
http://api.college.com/students/3248234/courses/2005/fall

Dateinamenerweiterungen sollten nicht verwendet werden, um die Formatvorgabe anzugeben. REST-API-Clients sollten ermutigt werden, die von HTTP zur Verfügung gestellten Formatauswahlmechanismen zu nutzen und den Anforderungs-Header anzunehmen und zu verarbeiten.

Um einfache Links und ein einfaches Debugging zu ermöglichen, kann eine REST-API die Medientyp-Auswahl über einen Abfrageparameter unterstützen, diese Option sollte jedoch mit Bedacht und vor allem mit Prüfungen zu den Standart-Header-Werten eingebaut werden.

Regel #7: Soll der Endpunktname Singular oder Plural sein?

Hier gilt die Keep-it-simple-Regel. Obwohl das innere Gefühl sagen wird, dass es falsch ist, eine einzelne Instanz einer Ressource mit einem Plural zu beschreiben, ist die pragmatische Antwort, das URI-Format konsistent zu halten und immer einen Plural zu verwenden!

Sich nicht mit der seltsamen Pluralisierung (person/people, goose/geese) auseinandersetzen zu müssen, macht das Leben des API-Clients besser und ist für den API-Provider einfacher zu implementieren (da die meisten modernen Frameworks nativ /students und /students/3248234 unter einer gemeinsamen Steuerung handhaben werden).

Aber wie gehen wir mit Beziehungen unter den Ressourcen um? Wenn eine Beziehung nur in einer anderen Ressource existieren kann, bieten die RESTful-Prinzipien nützliche Hinweise. Ein Beispiel veranschaulicht es: Ein Student hat eine Reihe von Kursen. Diese Kurse werden logisch auf den /stundents-Endpunkt wie folgt abgebildet:

https://api.college.com/students/3248234/courses
Ruft eine Liste aller Kurse ab, die von einem Schüler mit ID 3248234 gelernt werden.

https://api.college.com/students/3248234/courses/physics
Ruft den Kurs Physik für einen Schüler mit ID 3248234 ab.

Schlussfolgerung

- Wenn Sie REST-API-Dienste entwerfen, müssen Sie auf Ressourcen achten, die von URIs definiert werden.

- Jede Ressource in einem Dienst wird mindestens einen URI identifizieren. Es ist am besten, wenn diese URI Sinn macht und die Ressource adäquat beschreibt.

- URIs sollten einer vorhersagbaren, hierarchischen Struktur folgen, um die Verständlichkeit zu verbessern und daher die Usability: vorhersehbar in dem Sinne, dass sie konsistent sind, hierarchisch in dem Sinne, dass Daten Strukturbeziehungen haben.

- RESTful APIs sind für die Verbraucher geschrieben. Der Name und die Struktur der URIs sollten den Verbrauchern eine Bedeutung vermitteln. Wenn die oben genannten Regeln befolgt werden, entsteht eine viel sauberere REST-API mit einem viel glücklicheren Kunden. Dies ist keine REST-Regel oder Einschränkung, aber es verbessert die API.

 

Schnittstellen sind für Kunden, nicht für Daten.

 

aus der Technik - Simon & Simon GbR
Luisenstraße 61
63067 Offenbach am Main

Tel: 069 800.88.702
eMail: hallo(at)ausdertechnik.de
URL: https://www.ausdertechnik.de