Support an RPC structure of API

[SvyatoslavVasiliev]

Hi there!
I am realy sad that OpenAPI specification does not support RPC style of API, because of path centric structure. There is so many tools to describe REST API, but there is no such to describe RPC API. And recently your initiative have appeared with Open API ideology, but without supporting of RPC API style. Why? Could you add it to nearest release?

[webron]

RPC style APIs could be a side effect of #574. An unfortunate side effect, IMHO.

[SvyatoslavVasiliev]

@webron it seems like that implementation of operations really solves issue of describing RPC API. There is can be some details related to JSON RPC 2.0, for example, but I hope you cover most cases.
Thank you, and if it possible to take part in testing of your new realease, I would glad to join.

[webron]

Parent: #586.

[webron]

Following a different thread, it's unlikely #574 will resolve it as it's controlled by the content of the request, not the structure of it. Moving it under #586.

[vearutop]

I use swagger spec to describe JSON-RPC in a hacky way, storing method names in paths keys and ignoring non-post operations. Hack is enabled by x-service-type vendored flag.

[earth2marsh]

@vearutop that sounds interesting—do you have an example you could share?

[vearutop]

basePath is used for endpoint value.
x-service-type specifies how to treat swagger.json file.
For this vendor extension we have a patched swagger-ui which envelopes original request to something like {"jsonrpc": "2.0", "method": "getSimpleV1", "params": {"id":3}, "id": 1}.
That simple we benefit from swagger spec and tools not only for our REST, but also for JSON-RPC services.

{
  "swagger": "2.0",
  "x-service-type": "json-rpc",
  "info": {
    "title": "DummyAPI",
    "version": "master~dirty"
  },
  "host": "",
  "basePath": "/rpc",
  "schemes": [
    "http",
    "https"
  ],
  "paths": {
    "getSimpleV1": {
      "post": {
        "tags": [
          "V1"
        ],
        "summary": "Simple Get",
        "description": "Get simple by ID",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/SimpleGetParameters"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "request success",
            "schema": {
              "$ref": "#/definitions/Simple"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Simple": {
      "type": "object",
      "properties": {
        "id_simple": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "SimpleGetParameters": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        }
      }
    }
  }
}

[wparad]

That's a little disappointing, I was really hoping to see something interesting, like folding of the parameters into the existing document, with clever uses of the flags. Having to use a different library to pull meaningful data is unfortunate.

[vearutop]

Sorry, @wparad, I did not mean to make you sad (mind hacky way disclaimer).
Not sure I got you right, by "folding of the parameters into the existing document" do you mean having JSON-RPC envelope structures built in schema definition? What is "different library"?

[SvyatoslavVasiliev]

@vearutop, could you clarify, your API has structure according to JSON RPC 2.0 or you are just using RPC style for URL resources?

[vearutop]

@SvyatoslavVasiliev, API is serving valid JSON RPC 2.0 structures.
JSON RPC enveloping (including batch requests) is done by client and server according to spec.
method, params and result is defined and validated by swagger.json path, post-parameters and post-responses-200 accordingly.
Endpoint URI is defined in swagger.json as basePath.
Service host is dynamic and loadbalanced, so it is not present in swagger.json.

Actually this swagger.json is not valid, since it does not have / at the beginning of paths keys.
But this approach made possible to achieve "compatibility" with least effort.

[SvyatoslavVasiliev]

@vearutop, thank you, as I am looking for some tool to specify my JSON RPC API, I will try your approach in swagger. But unfortunately, as @wparad already said, standard swagger library won't be able to work with it fully. For example if I try to upload your specification in on-line swagger editor I won't able to make API requests, because of wrong auto generated URL.