Api-blueprint: Necesita múltiples acciones del mismo verbo HTTP en el mismo recurso (pero diferente tipo de contenido de solicitud)

Actualización: encuentro que puedo hacer esto indicando solo una respuesta:

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

Sin embargo, esto no se muestra correctamente en el modo incrustado (solo muestra un tipo de solicitud). Las vistas de vista previa y documentación dentro del editor son buenas.

@jrep

Esto parece ser un deslucido en el incrustado (diseño) de Apiary actual. He notificado al equipo de

@jrep, ¿ está la solicitud aquí (junto a la limitación en incrustación) para admitir múltiples respuestas?

Si es así, lo siguiente ya debería ser válido:

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

Su ejemplo muestra múltiples solicitudes pero solo una única respuesta . Ese es mi ejemplo. Sí, eso es sintácticamente válido, pero no es capaz de expresar lo que necesitamos expresar.

Sí: aquí es necesario mostrar una "Respuesta 200" diferente para cada solicitud. El tipo de contenido de respuesta coincide con el tipo de contenido de la solicitud (por lo que dos tipos de contenido de solicitud significan dos tipos de contenido de respuesta), pero también la información en las dos respuestas no es exactamente equivalente.

Con el formato heredado, definimos una solicitud y su respuesta, luego el siguiente par solicitud / respuesta. Eso es un error de sintaxis en el nuevo formato, y no parece haber ninguna forma válida de decirlo.

Actualización: Vaya, no miré lo suficientemente cerca: su ejemplo es diferente al mío en al menos dos formas: dos respuestas y el uso de solicitudes con nombre. Intentando eso ahora.

@jrep

No estoy seguro de cómo lo dices en serio. ¿Puede enviar aquí un fragmento del modelo heredado?

El ticket de Github no me permite adjuntar texto. Puede obtener el plano heredado en https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib

Entiendo

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

Creo que está fundamentalmente bien expresar esto como:

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

Este es un ejemplo clásico de negociación de contenido. Cree un recurso a partir de muchas representaciones diferentes, mientras que la respuesta no tiene cuerpo y solo dice OK (y quizás un enlace a él).

La contraparte de la negociación de contenido sería:

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

Creo que una respuesta sin cuerpo a múltiples solicitudes que difiere en el tipo de contenido pero que tiene el mismo significado (crear un recurso) es el buen diseño. Sin embargo, quiero levantar esta restricción (de advertencia cuando hay varias respuestas con el mismo estado y tipo de contenido) con la implementación de https://github.com/apiaryio/snowcrash/issues/53

@jrep Este problema se abordó en https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0), por lo tanto, lo estoy cerrando. Comente y vuelva a abrir si es necesario.

Aunque un punto final puede tener múltiples ejemplos de transacciones, como se ve en apiaryio / snowcrash # 53, estos no se

Tome el siguiente ejemplo ...

Tiene /oauth2/authorize , que por especificación manejará varios escenarios diferentes (como obtener un token de acceso desde una actualización o generar un token a partir de una contraseña, etc.). Tenerlos combinados en una sola acción en los documentos de la API es muy difícil de entender para el lector, en cambio, es más fácil para el usuario tener múltiples puntos finales como "Actualizar token de acceso" y "Autenticar usuario" en el menú lateral. Sin embargo, esto no es posible porque no puede especificar la misma combinación de método / URL dos veces.

Este es un excelente ejemplo de dónde la Especificación de API está obligando a sus desarrolladores a utilizar un enfoque determinado y, en casos como el anterior, no encaja con los patrones de diseño comunes.

Veo resaltado de sintaxis incorrecto - veo el color de Body :