Api-blueprint: Besoin de plusieurs actions du même verbe HTTP sur la même ressource (mais un type de contenu de requête différent)

Mise à jour : je trouve que je peux le faire en ne déclarant qu'une seule réponse :

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

Cependant, cela ne s'affiche pas correctement en mode intégré (n'affiche qu'un seul type de demande). Les vues Aperçu et Documentation dans l'éditeur sont bonnes.

@jrep

Cela semble être terne dans l'intégration actuelle du rucher (conception). J'ai informé l'équipe @apiaryio de ce problème.

@jrep est la demande ici (à côté de la limitation dans l'intégration) pour prendre en charge plusieurs réponses ?

Si tel est le cas, ce qui suit devrait déjà être valide :

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

Votre exemple montre plusieurs demandes mais une seule réponse . C'est exactement comme mon exemple. Oui, c'est syntaxiquement valide, mais il n'est pas capable d'exprimer ce que nous devons exprimer.

Oui : il s'agit ici d'afficher une "Réponse 200" différente pour chaque requête. Le type de contenu de la réponse correspond au type de contenu de la demande (donc deux types de contenu de demande signifient deux types de contenu de réponse), mais également les informations dans les deux réponses ne sont pas exactement équivalentes.

Avec le format Legacy, nous avons défini une requête et sa réponse, puis la paire requête/réponse suivante. C'est une erreur de syntaxe dans le nouveau format, et il ne semble pas y avoir de moyen valable de le dire.

Mise à jour : Oups, je n'ai pas regardé d'assez près : votre exemple est différent du mien d'au moins deux manières : deux réponses, et l'utilisation de requêtes nommées. J'essaye ça maintenant.

@jrep

Je ne sais pas comment vous l'entendez. Pouvez-vous s'il vous plaît soumettre ici un extrait de l'ancien plan ?

Le ticket Github ne me permet pas de joindre du texte. Vous pouvez obtenir le modèle hérité de https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib

J'ai compris

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

Je pense qu'il est fondamentalement correct d'exprimer cela comme suit :

## 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

Il s'agit d'un exemple classique de négociation de contenu. Créez une ressource à partir de nombreuses représentations différentes alors que la réponse n'a pas de corps et indique simplement OK (et peut-être un lien vers celle-ci).

La contrepartie de la négociation de contenu serait :

### 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 ...

Je pense qu'une réponse sans corps à plusieurs demandes qui diffère par le type de contenu mais qui ont la même signification (créer une ressource) est la bonne conception. Cependant, je souhaite lever cette restriction (d'avertissement lorsqu'il y a plusieurs réponses avec le même statut et le même type de contenu) avec la mise en œuvre de https://github.com/apiaryio/snowcrash/issues/53

@jrep Ce problème a été résolu dans https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0) donc je le ferme. Veuillez commenter et rouvrir si nécessaire.

Bien qu'un point de terminaison puisse avoir plusieurs exemples de transactions, comme on le voit dans apiaryio/snowcrash#53, ceux-ci ne

Prenons l'exemple suivant...

Vous avez /oauth2/authorize , qui par spécification gérera différents scénarios (tels que l'obtention d'un jeton d'accès à partir de l'actualisation, ou la génération d'un jeton à partir d'un mot de passe, etc.). Les fusionner en une seule action sur les documents de l'API est très difficile à comprendre pour le lecteur, mais il est plus facile pour l'utilisateur d'avoir plusieurs points de terminaison tels que "Actualiser le jeton d'accès" et "Authentifier l'utilisateur" dans le menu latéral. Cependant, cela n'est pas possible car vous ne pouvez pas spécifier deux fois la même combinaison méthode/URL.

Il s'agit d'un excellent exemple où la spécification de l'API oblige ses développeurs à utiliser une certaine approche et, dans des cas comme celui ci-dessus, ne correspond pas aux modèles de conception courants.

Je vois un surlignage de syntaxe incorrect - voir la couleur de Body :