Api-blueprint: Admite la sobrecarga de URI para JSON-RPC

Moviéndose a apiary.io.

@rodriguise ¿Dónde puedo encontrar información sobre este problema? Tengo el mismo pensamiento, sería una buena característica admitir API similares a RPC.

@rodriguise También estoy muy interesado en esta funcionalidad, ¿podría decirme dónde puedo aprender sobre este problema?

@adammbalogh @SvyatoslavVasiliev ¿Pueden describir su caso de uso un poco más?

@pksunkara seguro.
Tengo una API diseñada de acuerdo con la especificación JSON-RPC 2.0 , por ejemplo:

PUBLICAR 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"
    }
  }
}

Dicha API tiene solo una URL para el grupo de métodos, donde los nombres de los métodos están contenidos en el cuerpo, en el parámetro "método".
La realización de Blueprint actual no permite describir dicha API, debido a la estructura del lenguaje centrada en la ruta.

Hola @pksunkara , ¿tienes alguna noticia sobre esto?
He intentado usar otras herramientas de renderizado (aglio, por ejemplo) en lugar de colmenar, y representaron la documentación correctamente, en contraste con el colmenar. Pero esas herramientas no admiten la representación de algunas funciones como Atributos como una sección separada.
Sería muy bueno si me ayudaras a resolver mi problema.

Hola @SvyatoslavVasiliev, así que si leo esto correctamente, un soporte para JSON RPC está incluido en https://github.com/apiaryio/api-blueprint/issues/289 aunque, técnicamente, el protocolo sigue siendo HTTP.

Desacoplar los recursos y las definiciones de acción de los URI y los métodos HTTP también debería ayudar en este caso.

¿Tiene sentido esto? Consulte el n. ° 289 para obtener detalles adicionales.

Hola @zdne ,
He intentado entender el número 289, pero no puedo entenderlo por completo.
Mi API usa HTTP con el cuerpo JSON como transporte, pero solo tiene una URL y solo usa HTTP POST. Toda la información sobre el recurso y el método contenida en el parámetro "método" en el cuerpo.
Por ejemplo, obtenga entidad:
{ "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" } } }

eliminar entidad:
{ "jsonrpc": "2.0", "id": 1, "method": "entity.delete", "params": { "id": "123" } }

Ambos métodos llamados HTTP POST http://myservice.com/rpcapi

Hasta ahora no he encontrado una forma moderna y funcional de documentar una API JSON-RPC (que también puedo usar para generar pruebas). Mi esperanza era API Blueprint, pero parece que realmente no es compatible. ¿Alguien conoce los planes futuros de API Blueprint de esto o tiene una sugerencia para una estructura / herramienta diferente que lo respalde?

@Dynom puedo dar consejos de pareja.
Puede probar Aglio render for api blueprint, no muestra la sección de atributos, pero muestra correctamente la estructura del documento.
Otra herramienta es API Doc , la estoy probando en el momento actual y me parece adecuada.

Gracias @SvyatoslavVasiliev No quiero usar soluciones de documentación en línea y API Doc anuncia que es para servicios RESTful, así que no estoy seguro de que podamos esperar mucho de eso a largo plazo.