Api-blueprint: Benötigen Sie mehrere Aktionen desselben HTTP-Verbs für dieselbe Ressource (aber unterschiedlicher Anforderungsinhaltstyp)

Update: Ich finde, dass ich dies tun kann, indem ich nur eine Antwort gebe:

FORMAT: 1A
# multiple posts?
## Try to make two posts [/v1/whatever]
### POST
+ Request JSON (application/json)
        { nil: nil }
+ Request DNS (text/dns)
        whatever
+ Response 204

Dies wird jedoch im eingebetteten Modus nicht korrekt angezeigt (zeigt nur einen Anforderungstyp an). Vorschau- und Dokumentationsansichten im Editor sind gut.

@jrep

Dies scheint in der aktuellen Apiary-Einbettung (Design) glanzlos zu sein. Ich habe das @apiaryio- Team über dieses Problem informiert.

@jrep ist die Anfrage hier (neben der Einschränkung in embed), um mehrere Antworten zu unterstützen?

Falls ja sollte folgendes bereits gültig sein:

FORMAT: 1A

## Try to make two posts [/v1/whatever]

### POST

+ Request JSON (application/json)

        JSON

+ Response 200 (application/json)

        JSON       

+ Request DNS (text/dns)

        whatever

+ Response 200 (text/dns)

        whatever

Ihr Beispiel zeigt mehrere Anfragen, aber nur eine einzige Antwort . Das ist genau wie mein Beispiel. Ja, das ist syntaktisch gültig, aber es kann nicht ausdrücken, was wir ausdrücken müssen.

Ja: Hier muss für jede Anfrage eine andere "Response 200" angezeigt werden. Der Inhaltstyp der Antwort stimmt mit dem Inhaltstyp der Anfrage überein (also zwei Inhaltstypen der Anfrage bedeuten zwei Inhaltstypen der Antwort), aber auch die Informationen in den beiden Antworten sind nicht genau äquivalent.

Beim Legacy-Format haben wir eine Anfrage und ihre Antwort definiert, dann das nächste Anfrage/Antwort-Paar. Das ist ein Syntaxfehler im neuen Format, und es scheint keine gültige Möglichkeit zu geben, dies zu sagen.

Update: Ups, ich habe nicht genau genug hingesehen: Ihr Beispiel unterscheidet sich in mindestens zweierlei Hinsicht von meinem: zwei Antworten und die Verwendung benannter Anfragen. Versuche das jetzt.

@jrep

Ich bin mir nicht sicher, wie du das meinst. Könnten Sie bitte hier einen Ausschnitt des alten Bauplans einreichen?

Mit dem Github-Ticket kann ich keinen Text anhängen. Sie können den Legacy-Blueprint von https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib abrufen

Ich habs

POST /v1/zones/{zone}
> Content-Type: application/json
... some data ...
< 204
< Location: /v1/zones/example.com

POST /v1/zones/{zone}
> Content-Type: text/dns
... some other data ...
< 204
< Location: /v1/zones/example.com

Ich denke, es ist grundsätzlich in Ordnung, dies so auszudrücken:

## Zone [/v1/zones/{zone}]

### Create [POST]

+ Request Create with JSON (application/json)

        { ... json data ... }

+ Request Create with DNS (text/dns)

        ... dns data ...

+ Response 204
    + Headers

            Location: /v1/zones/example.com

http://docs.multirequest.apiary.io

Dies ist ein klassisches Content-Negotiation-Beispiel. Erstellen Sie eine Ressource aus vielen verschiedenen Darstellungen, während die Antwort keinen Text hat und nur OK (und möglicherweise einen Link dazu) anzeigt.

Das Gegenstück zur Inhaltsverhandlung wäre:

### Retrieve [GET]

+ Request Rerieve JSON representation
    + Headers

            Accept: application/json

+ Response 200 (application/json)

        { ... json data ... }

+ Request Rerieve DNS representation
    + Headers

            Accept: text/dns

+ Response 200 (text/dns)

        ... dns data ...

Ich denke, eine körperlose Antwort auf mehrere Anfragen, die sich im Inhaltstyp unterscheiden, aber die gleiche Bedeutung haben (eine Ressource erstellen), ist das gute Design. Ich möchte diese Einschränkung (der Warnung bei mehreren Antworten mit demselben Status und Inhaltstyp) jedoch mit der Implementierung von https://github.com/apiaryio/snowcrash/issues/53 aufheben

@jrep Dieses Problem wurde in https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0) behoben, daher schließe ich es. Bitte kommentieren und bei Bedarf wieder öffnen.

Obwohl ein Endpunkt mehrere Transaktionsbeispiele haben kann, wie in apiaryio/snowcrash#53 zu sehen, werden diese in Apiary nicht sehr sauber gerendert.

Nehmen Sie das folgende Beispiel...

Sie haben /oauth2/authorize , das laut Spezifikation verschiedene Szenarien handhabt (z. B. das Abrufen eines Zugriffstokens aus der Aktualisierung oder das Generieren eines Tokens aus einem Kennwort usw.). Diese zu einer einzigen Aktion in den API-Dokumenten zusammenzuführen, ist für den Leser sehr schwer zu verstehen, stattdessen ist es für den Benutzer einfacher, mehrere Endpunkte wie "Zugriffstoken aktualisieren" und "Benutzer authentifizieren" im Seitenmenü zu haben. Dies ist jedoch nicht möglich, da Sie dieselbe Methode/URL-Kombination nicht zweimal angeben können.

Dies ist ein Paradebeispiel dafür, dass die API-Spezifikation ihre Entwickler zu einem bestimmten Ansatz zwingt und in Fällen wie den oben genannten nicht zu gängigen Designmustern passt.

Ich sehe eine falsche Syntaxhervorhebung - siehe die Farbe von Body :