Api-blueprint: Precisa de várias ações do mesmo verbo HTTP no mesmo recurso (mas diferentes tipos de conteúdo de solicitação)

Atualização: acho que posso fazer isso declarando apenas uma resposta:

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

No entanto, isso não é exibido corretamente no modo incorporado (mostra apenas um tipo de solicitação). As visualizações de visualização e documentação dentro do editor são boas.

@jrep

Isso parece ser um pouco sem brilho na incorporação (design) do Apiário atual. Notifiquei a equipe

@jrep é a solicitação aqui (ao lado da limitação em embed) para oferecer suporte a respostas múltiplas?

Nesse caso, o seguinte já deve 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

Seu exemplo mostra várias solicitações, mas apenas uma única resposta . É exatamente como meu exemplo. Sim, isso é sintaticamente válido, mas não é capaz de expressar o que precisamos expressar.

Sim: a necessidade aqui é mostrar uma "Resposta 200" diferente para cada solicitação. O tipo de conteúdo de resposta corresponde ao tipo de conteúdo de solicitação (portanto, dois tipos de conteúdo de solicitação significam dois tipos de conteúdo de resposta), mas também as informações nas duas respostas não são precisamente equivalentes.

Com o formato Legacy, definimos uma solicitação e sua resposta e, em seguida, o próximo par solicitação / resposta. Esse é um erro de sintaxe no novo formato e não parece haver nenhuma maneira válida de dizer isso.

Atualização: Opa, eu não olhei perto o suficiente: seu exemplo é diferente do meu em pelo menos dois aspectos: duas respostas e uso de solicitações nomeadas. Tentando agora.

@jrep

Não tenho certeza de como você quer dizer isso. Você pode enviar aqui um trecho do projeto legado?

O tíquete do Github não me deixa anexar texto. Você pode obter o blueprint legado em https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib

Entendi

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

Acho que é fundamentalmente correto expressar isso 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 é um exemplo clássico de negociação de conteúdo. Crie um recurso a partir de muitas representações diferentes enquanto a resposta não tem corpo e apenas indica OK (e talvez um link para ela).

A contrapartida de negociação de conteúdo para isso seria:

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

Acho que uma resposta sem corpo a várias solicitações que diferem no tipo de conteúdo, mas têm o mesmo significado (criar um recurso) é o bom design. No entanto, desejo retirar essa restrição (de aviso quando houver várias respostas com o mesmo status e tipo de conteúdo) com a implementação de https://github.com/apiaryio/snowcrash/issues/53

@jrep Este problema foi resolvido em https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0), portanto, estou encerrando. Comente e reabra se necessário.

Embora um endpoint possa ter vários exemplos de transação, como visto em apiaryio / snowcrash # 53, eles não são renderizados de forma muito limpa no Apiary.

Veja o seguinte exemplo ...

Você tem /oauth2/authorize , que por especificação lidará com vários cenários diferentes (como obter um token de acesso a partir da atualização ou gerar um token a partir da senha, etc.). Ter isso mesclado em uma única ação nos documentos da API é muito difícil para o leitor entender; em vez disso, é mais fácil para o usuário ter vários pontos de extremidade, como "Atualizar token de acesso" e "Autenticar usuário" no menu lateral. No entanto, isso não é possível porque você não pode especificar a mesma combinação de método / URL duas vezes.

Este é um excelente exemplo de onde a Especificação da API está forçando seus desenvolvedores a usar uma determinada abordagem e, em casos como o acima, não se encaixa nos padrões de design comuns.

Vejo destaque de sintaxe incorreta - veja a cor de Body :