Discussion on: Are there any API specification formats for WebSockets?

[Idan Arye]

I'm not looking for a subprotocol - what I'm looking for is more of an API specification.

Consider, for example, this JSON-RPC example (taken from Wikipedia):

// Request:
{
    "jsonrpc": "2.0",
    "method": "subtract",
    "params": {
        "minuend": 42,
        "subtrahend": 23
    },
    "id": 3
}
// Response:
{
    "jsonrpc": "2.0",
    "result": 19,
    "id": 3
}

The JSON-RPC protocol says:

• The request:
  • Should be a JSON object.
  • Should have a jsonrpc string field that defines the JSON-RPC protocol version.
  • Should have an (automatically generated) id integer field that identifies the message.
  • Should have a method string field that says what command you want to call.
  • Should have a params object(/array) field that provides parameters for the command.
• The response:
  • Should be a JSON object.
  • Should have a jsonrpc string field that defines the JSON-RPC protocol version.
  • Should have an id integer field that is the same as the request it responds to.
  • Should have a result field that holds the result of the request.

What I'm looking for is something that'll allow me to define:

• There is a subtract method:
  • It should have a minuend numeric parameter that specifies the number to subtract from.
  • It should have a subtrahend numeric parameter that specifies the number to subtract.
  • It returns a number, which is the difference between these numbers.
  • Possibly some doc text with some markup?

OpenAPI and OData seem to have that, but they are REST-centric. XML-RPC has this, but being XML it is needlessly complicated and burdensome. I was hoping to find something similar to AsyncAPI - though if there is something, maybe the fact it cannot be easily found implies that it will not have wide language support either...