Viertens war manches, was mir dazu erklärt wurde, schlicht erfunden.
Die Szene kennst du aus dem Prolog: Du fragst nach und bekommst einen zweiten Codeblock, der dem ersten widerspricht, beide gleich überzeugt.
Das ist kein böser Wille. Es ist Kapitel 1 in Aktion. Ein Modell hat Dokumentationen vieler Anbieter aus vielen Jahren gelesen. Sie sehen sich ähnlich, und ihre Feldnamen verschwimmen in der wahrscheinlichsten Fortsetzung zu etwas, das plausibel klingt und in keiner einzigen Schnittstelle genau so existiert. Das Modell setzt fort. Es schlägt nicht nach, außer man gibt ihm die aktuelle Dokumentation in den Kontext.
Dieses Kapitel ist das, was ich mir damals gewünscht hätte: einmal den ganzen Brief, vollständig, von beiden Seiten, mit dem, was jedes Feld im Produkt bewirkt. Du wirst danach kein JSON auswendig können. Du wirst es lesen können, und das reicht für fast alles, was in diesem Buch noch kommt.
Was eine API ist
Eine API legt fest, welche Angaben Software bei einem Aufruf übergeben kann und wie die Rückgabe aufgebaut ist. Man kann sie sich wie die Regeln einer Poststelle vorstellen: wohin der Brief geht, was auf den Umschlag gehört, wie der Inhalt aufgebaut sein muss und in welcher Form die Antwort zurückkommt.