Idan Arye

Posted on May 1, 2019

Are there any API specification formats for WebSockets?

#help #websocket #api

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. They can be strings or blobs, but how these strings/blobs are structured is left to the user.

This is not a bad thing - you want this layer of abstraction to be simple so it'll be easy to implement and to build on - but with HTTP - which is similar in that way (you can only send plaintext with some headers) there are many protocols built on top of it that add this structure: OpenAPI, OData, XML-RPC and many more.

Some of these protocols offer schema generators - you write your protocol's specification once in the protocol's favorite format, and it generates types and/or functions for using your protocol in many different languages.

I tried looking for something similar for WebSocket, but all I could find is AsyncAPI. It has a generator, which can output using templates - but it only has templates for Java (Spring, actually), HTML and Markdown (the last two are for generating docs) and googling for third-party templates yielded nothing (except results from their issue tracker, which has some requests to add templates for more languages).

Is there anything more complete than AsyncAPI? If this is the best we have I'll use that - good documentation generation is already a bonus, and I can probably contribute myself templates for the languages I use - but if there is something better I'd rather just use that.

Top comments (11)

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

Phil Ashby • May 2 '19

Good question! I found that the IANA operate a registry of subprotocols: iana.org/assignments/websocket/web...

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

Phil Ashby • May 3 '19

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 • 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?

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.

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

DEV Community

Are there any API specification formats for WebSockets?

Top comments (11)

Read next

Gentle introduction to IDataProtector (C#)

What is JSON

How WordPress REST API can improve your Business Website?

Routing implementation using PHP attributes