infrastructure-api-repository.zalandoapis.com/ (internes Repository von APIs) Open API unterstützt Sie nicht bei der formalen Angabe verschiedener Rückgabeobjektschemas, abhängig von einem Parameter. Wenn Sie den Feldparameter definieren, empfehlen wir, die folgende Beschreibung anzugeben: Endpoint unterstützt das Filtern von Rückgabeobjektfeldern, wie in [Regel #157] beschrieben(opensource.zalando.com/restful-api-guidelines/#157) Hinweis: Um ein konsistentes Erscheinungsbild von Paginierungsmustern zu gewährleisten, müssen Sie sich an die allgemeinen Abfrageparameternamen halten, die in MUST-Stick an herkömmliche Abfrageparameter definiert sind. Begründung: Es gibt keinen etablierten Industriestandard, aber viele beliebte Internet-Unternehmen bevorzugen snake_case: z.B. GitHub, Stack Exchange, Twitter. Andere, wie Google und Amazon, verwenden beides – aber nicht nur camelCase. Es ist wichtig, ein konsistentes Aussehen und Gefühl zu etablieren, so dass JSON aussieht, als ob es aus der gleichen Hand kam. Versionsinformationen und Medientyp werden zusammen über den HTTP Content-Type-Header bereitgestellt, z.B. application/x.zalando.cart+json;version=2. Bei inkompatiblen Änderungen wird eine neue Medientypversion für die Ressource erstellt. Um die neue Darstellungsversion zu generieren, können Verbraucher und Produzent Inhaltsaushandlungen mithilfe der HTTP Content-Type- und Accept-Header ausführen. Hinweis: Da die korrekte Implementierung von PATCH etwas schwierig ist, empfehlen wir dringend, ein und nur eines der folgenden Muster pro Endpunkt auszuwählen, es sei denn, es wird durch eine rückwärtskompatible Änderung erzwungen. In Vorzugsreihenfolge: Der Name eines Attributs, das ein solches HttpLink-Objekt enthält, gibt die Beziehung zwischen dem Objekt an, das die Verknüpfung enthält, und der verknüpften Ressource. Implementierungen sollten bei Bedarf Namen aus der IANA Link Relation Registry verwenden.
Da IANA-Linkbeziehungsnamen eine Bindestrich-Fallnotation verwenden, während dieses Handbuch snake_case Notation für Attributnamen erzwingt, Bindestriche in IANA-Namen müssen durch Unterstriche ersetzt werden (z.B. würde die IANA-Link-Beziehungs-Versionsversion zum Attribut version_history) Bitte beachten Sie die folgenden Regeln für detaillierte funktionale Namensmuster: In vielen Fällen ist es hilfreich oder sogar notwendig, POST und PATCH idempotent für Clients zu entwerfen, um Konflikte aufzudecken und Ressourcenduplikate (auch Zombie-Ressourcen genannt) oder verlorene Aktualisierungen zu verhindern, z.B. wenn dieselben Ressourcen erstellt oder mehrfach geändert werden können. Um einen idempotenten API-Endpunkt zu entwerfen, sollten Besitzer eines der folgenden drei Muster anwenden. Eine API wird veröffentlicht, indem die Open API-Spezifikation in das reservierte /zalando-apis-Verzeichnis des Bereitstellungsartefakts kopiert wird, das zum Bereitstellen des Bereitstellungsdiensts verwendet wird. Das Verzeichnis darf nur eigenständige YAML-Dateien enthalten, die jeweils eine API beschreiben (Ausnahme siehe MUST nur dauerhafte und unveränderliche Remoteverweise verwenden).