Eine Schnittstelle entwerfen, mit der man leben kann
Konsistenz vor Schönheit
Dieselbe Namenskonvention auf jeder Route, dieselbe Antwortstruktur, dasselbe Datumsformat, dieselbe Fehlerstruktur. Zehn konsistente Routen sind leichter als fünf brillante und fünf verschiedene.
Geben Sie eine stabile Struktur zurück: ein Hüllobjekt mit Daten und Metadaten, damit man Felder hinzufügen kann, ohne zu brechen.
Entscheidungen, die zu Ihnen zurückkehren
Seitennummerierung. Entscheiden Sie im Voraus — nach Position oder nach Cursor — und unterstützen Sie sie in jeder Liste. Listen ohne Seitennummerierung wachsen stets über das Erwartete hinaus.
Filtern und Sortieren. Definiert und dokumentiert, kein freies Feld, in dem jeder Verbraucher Regeln erfindet.
Kennungen. Stabil, nicht fortlaufend, und keine Geschäftsinformation in ihrer Zahl offenlegend.
Fehler sind Teil des Vertrags
Ein korrekter Statuscode, eine feste Fehlerkennung, auf die man Logik verzweigen kann, eine lesbare Meldung und eine Anfragekennung zur Untersuchung. Eine Schnittstelle, die je Fehler unterschiedlichen Freitext zurückgibt, zwingt den Verbraucher, Zeichenketten zu prüfen.
Im Detail
Dokumentieren Sie die Schnittstelle aus dem Code selbst, damit die Doku nicht altert, und stellen Sie eine Testumgebung mit Dummy-Daten bereit. Und vor der Veröffentlichung: Lassen Sie jemanden, der die Schnittstelle nicht schrieb, ein vollständiges Szenario dagegen umsetzen — jede Frage, die er stellt, ist ein Entwurfsfehler, keine Wissenslücke.