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...

[Phil Ashby]

Understood, and apologies for a very terse comment (I was on my mobile on a train..) I commented as I did not know that there was a formal registry of sub-protocols so I wanted to bring this list to people's attention in case, like myself, they were unaware of them.

Looking at the published list I see things like WAMP (wamp-proto.org/) or even (god forbid) SOAP (docs.microsoft.com/en-us/openspecs...), which may well provide both a protocol specification and a client-side API / implementation that meets your needs.

[Idan Arye]

I need to take some time to read the WAMP specs, but TBH it's kind of intimidating. If the spec doc is that long it probably complicated to implement, but if most of the majority fo that complexity is to implement security then it's worth it...

I'm not going to touch SOAP because I already know it's complicated for the sake of complicatedness.

Another option is to use Protocol Buffers' services to define the API and build a simple protocol (maybe use JSON-RPC? But with ProtoBuf?) that uses these?