Api-blueprint: Suporta sobrecarga de URI para JSON-RPC

Movendo-se para apiary.io.

@rodriguise Onde posso encontrar informações sobre esse problema? Eu tenho o mesmo pensamento, seria um bom recurso oferecer suporte a APIs semelhantes a RPC.

@rodriguise Também estou muito interessado nesta funcionalidade, poderia dizer onde posso aprender sobre este assunto?

@adammbalogh @SvyatoslavVasiliev Vocês podem descrever seu caso de uso um pouco mais?

@pksunkara com certeza.
Tenho uma API projetada de acordo com a especificação JSON-RPC 2.0 , por exemplo:

POST http://somehost.com/rpc_api

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "entity.get",
  "params": {
    "filter": {
      "filters": [
        {
          "field": "name",
          "operator": "eq",
          "value": "Bob"
        },
        {
          "field": "age",
          "operator": "eq",
          "value": 25
        }
      ],
      "condition": "and"
    }
  }
}

Tal API possui apenas um URL para grupo de métodos, onde os nomes dos métodos estão contidos no corpo, no parâmetro "método".
A realização atual do Blueprint não permite descrever tal API, devido à estrutura de linguagem centrada no caminho.

Olá @pksunkara , você tem novidades sobre isso?
Tentei usar outras ferramentas de renderização (aglio, por exemplo) em vez de apiário, e elas representaram a documentação corretamente, ao contrário do apiário. Mas essas ferramentas não oferecem suporte à renderização de alguns recursos, como Atributos, como seções separadas.
Seria muito bom se você me ajudasse a resolver meu problema.

Olá @SvyatoslavVasiliev, então se eu li isso corretamente, um suporte para JSON RPC está caindo em https://github.com/apiaryio/api-blueprint/issues/289 , embora, tecnicamente, o protocolo ainda seja HTTP.

Separar os recursos e as definições de ação de URIs e métodos HTTP também deve ajudar neste caso.

Isso faz sentido? Por favor, veja # 289 para detalhes adicionais

Olá @zdne ,
Tentei entender o nº 289, mas não consigo entendê-lo completamente.
Minha API usa HTTP com corpo JSON como transporte, mas tem apenas uma URL e usa apenas HTTP POST. Todas as informações sobre o recurso e o método contidas no parâmetro "método" no corpo.
Por exemplo, get entity:
{ "jsonrpc": "2.0", "id": 1, "method": "entity.get", "params": { "filter": { "filters": [ { "field": "name", "operator": "eq", "value": "Bob" }, { "field": "age", "operator": "eq", "value": 25 } ], "condition": "and" } } }

excluir entidade:
{ "jsonrpc": "2.0", "id": 1, "method": "entity.delete", "params": { "id": "123" } }

Ambos os métodos são chamados de HTTP POST http://myservice.com/rpcapi

Até agora não encontrei uma maneira moderna e funcional de documentar uma API JSON-RPC (que também possa usar para gerar testes). Minha esperança era o API Blueprint, mas parece que não é realmente compatível. Alguém conhece os planos futuros do API Blueprint deste ou tem uma sugestão de uma estrutura / ferramenta diferente que suporte isso?

@Dynom posso dar alguns conselhos.
Você pode tentar o Aglio render para Api Blueprint, ele não renderiza a seção de atributos, mas exibe corretamente a estrutura do documento.
Outra ferramenta é o API Doc , estou testando no momento e parece adequado.

Obrigado @SvyatoslavVasiliev . Não quero usar soluções de documentação inline e o API Doc anuncia que é para serviços RESTful, então não tenho certeza se podemos esperar muito disso a longo prazo.