DEV Community

Are there any API specification formats for WebSockets?

Idan Arye on May 01, 2019

The WebSocket protocol allows sending messages back-and-forth between a server and a client, but it does not define the structure of these messages...

Read full post

Idan Arye • May 2 '19

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

Nishchit • Oct 13 '19

AyncAPI is the closest specification for the streaming protocol like WebSocket, MQTT, and others. But it's still premature stage and growing standard. We're building Firecamp for streaming protocol testing.

you can give Firecamp a try. For the specification, we're working on it and most probably we'll keep it compatible with AsyncAPI specifications. You can import/export the project (including ws request) and review the custom specification (Firecamp format). Based on it we're generating the code snippets for different languages. you can see it in the screenshots.

We'll publish the WS specifications once it'll be more matured. Please keep sharing your feedbacks :)

Firecamp WS snippets

And here is how it looks like while testing WebSocket

Anbraten • Aug 19 '23

I am still looking for a similar schema framework for websockets as well. Graphql subscriptions is kind of bringing such a schema. I also recently discovered tRPC in case you are using JS / TS only.

Idan Arye • May 3 '19 • Edited

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?

Lukasz Gornicki • Mar 20 '20

Definitely AsyncAPI -> github.com/asyncapi/asyncapi/

We have many people asking about websockets in our slack asyncapi.com/slack-invite/

Idan Arye • Mar 20 '20

Still seems thin in the language support department - only thing added since I posted this almost a year ago is node.js templates.

I did find this ticket though - github.com/asyncapi/generator/issu... - which suggests using something like quicktype.io/. So maybe I should just use quicktype?

Lukasz Gornicki • Mar 20 '20

Last year was fully focused on releasing AsyncAPI 2.0, so getting the spec more mature.
This year we focus on tooling. Come and join us.

Quicktype will generate just types for you, this is why we want to integrate it in generator for code templates. But it cannot really replace generator.

What is that you exactly need except of the spec? What do you want to get out of the spec?

Idan Arye • Mar 20 '20

I need the specs to describe the methods that can be sent. Each method needs to describe:

Its name.
Its fields (and their possibly deep types)
What it returns.
Free text to describe what it does.

Ideally I'd like something that can generate the full API. For example, if I have

- name: foo
  parameters:
    - name: bar
      type: integer
    - name: baz
      type: text
  returns:
    - name: x
      type: float
    - name: y
      type: float
  doc: bla bla bla

It would generate, say for Java:

public class FooResult {
    private float x;
    private float y;

    public FooResult(float x, float y) {
        this.x = x;
        this.y = y;
    }

    public float getX() {
        return x;
    }

    public float getY() {
        return y;
    }
}

public abstract class AbstractAPI {
    protected abstract Value call(String method, Value parameters);

    /**
     * bla bla bla
     */
    public FooResult foo(int bar, String baz) {
        Value request = new Value();
        request.setInt("bar", bar);
        request.setString("baz", baz);

        Value result = call("foo", request);

        return FooResult(result.getFloat("x"), result.getFloat("y"));
    }
}

And then you'll just have to subclass AbstractAPI (yes, I know) and implement call and you'll get fully typed access to the entire API.

Lukasz Gornicki • Apr 22 '21

Hey, fyi I published some materials about WebSocket API and AsyncAPI github.com/asyncapi/spec/issues/25...

also, for code generation -> we released a new library for generating types/models. It can be used with our generator and also as a standalone. Long term we want to integrate it with new CLI so you can easily generate models from CLI -> github.com/asyncapi/generator-mode...