Api-blueprint: Support URI overloading for JSON-RPC

Moving to apiary.io.

@rodriguise Where can I find information about this issue? I have the same thought, it would be a nice feature to support RPC-like APIs.

@rodriguise I am very interested in this functionality too, could you say where I can learn about this issue?

@adammbalogh @SvyatoslavVasiliev Can you guys describe your use case a bit more?

@pksunkara sure.
I have API designed according JSON-RPC 2.0 Specification, for example:

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

Such API has only one URL for methods group, where methods' names are contained in body, in "method" parameter.
Current Blueprint realisation doesn't allow describe such API, because of path-centric language structure.

Hi @pksunkara, do you have any news about this?
I have tried use other rendering tools (aglio for example) instead apiary, and they represented documentation correctly, in contrast to apiary. But those tools don't support rendering some features like Attributes as separate section.
It would be very nice if you help solve my issue.

Hey @SvyatoslavVasiliev so if I read this correctly a support for JSON RPC is falling under the https://github.com/apiaryio/api-blueprint/issues/289 albeit, technically the protocol is still HTTP.

Decoupling the resources and action definitions from URIs and HTTP methods should help this case as well.

Does this makes sense? Please see #289 for additional details

Hi @zdne,
I've tried to understand #289, but I am not able to understand it completely.
My API use HTTP with JSON body as transport, but it has only one URL and uses only HTTP POST. All information about resource and method contained in "method" param into body.
For example, 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" } } }

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

Both methods called as HTTP POST http://myservice.com/rpcapi

So far I haven't found a modern and functional way of documenting a JSON-RPC API (that I can also use to generate tests). My hope was API Blueprint but it seems that it's not really supported. Does anyone know the future plans of API Blueprint of this or have a suggestion for a different structure/tool that supports this?

@Dynom I can give couple advices.
You can try Aglio render for api blueprint, it does not render attributes section, but correctly displays document's structure.
Another tool is API Doc, I am testing it in current moment and it seems suitable.

Thanks @SvyatoslavVasiliev I don't want to use inline documentation solutions and API Doc advertises that it's for RESTful services, so I'm not sure if we can expect much from that in the long run.