Add websockets stream api docs

[illia-malachyn]

Closes onflow/flow-go#6644

• Added a single page overview docs
• Added a multi-page detailed docs for each message type

This is in progress and is postponed till we finish with websockets epic. However, you can review it and write notes about it.

What to add to:

• more examples with different parameters (after integration tests are finished)
• rate limits (when all limits are discussed and implemented)

[vercel]

@illia-malachyn is attempting to deploy a commit to the Flow Team on Vercel.

A member of the Team first needs to authorize it.

[illia-malachyn]

cc @peterargue @Guitarheroua @AndriiDiachuk

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 14, 2025 4:23pm

[franklywatson]

@illia-malachyn the deployed vercel from a few days ago is here.

With the left nav we probably want a top label that is more readable than "websockets-stream-api". This nav option is also distinct from the written title of 'Websockets Stream API'. My guess is the intention was for the sub pages to be under that root, not the 'websockets-stream-api' one

[franklywatson]

Nav looks good in latest vercel deployment. Looks like there's still more to be added and we should wait to merge this only once the functionality is deployed and live.

[franklywatson]

@illia-malachyn you will need to merge from main since the project structure for the docs in this area changed.

Also, we need to make sure this section is also updated: https://developers.flow.com/networks/access-onchain-data#subscriptions

[Guitarheroua]

@illia-malachyn you will need to merge from main since the project structure for the docs in this area changed.

Also, we need to make sure this section is also updated: https://developers.flow.com/networks/access-onchain-data#subscriptions

Created separate issue #1150 to fix the last part you mentioned, as I see we do not have any description of new gRPC subscriptions and do not mark the old implementation as deprecated.

[peterargue]

added a few more comments. otherwise this is good

[Guitarheroua]

added a few more comments. otherwise this is good

@peterargue fixed all remarks.

[illia-malachyn]

We need to add a page with common error codes and maybe examples so that clients can handle them properly

[illia-malachyn]

As we are polishing websockets and some errors may come up, I'd recommend you write an automated subscription script for every topic. By doing this, we could run all of them after each bugfix and see we didn't break anything in case integration tests don't cover some logic. This would work as an additional layer of testing as well as future documentation for clients.

Here's a small example you can use https://github.com/The-K-R-O-K/flow-stream-api-example/blob/main/template.js
You can commit every subscription request there.

I image sth like that:

examples/
  blocks/
    from_start_height.js
    from_start_id.js
    from_latest_block.js
    wrong_args.js
    handle_errors.js
  events/
    ...

Despite the fact that this is out of the scope of this issue and we have a separate issue for it. I can see no reason why to not do it right now. It is faster than testing websockets manually.

[Guitarheroua]

As we are polishing websockets and some errors may come up, I'd recommend you write an automated subscription script for every topic. By doing this, we could run all of them after each bugfix and see we didn't break anything in case integration tests don't cover some logic. This would work as an additional layer of testing as well as future documentation for clients.

Here's a small example you can use https://github.com/The-K-R-O-K/flow-stream-api-example/blob/main/template.js You can commit every subscription request there.

I image sth like that:

examples/
  blocks/
    from_start_height.js
    from_start_id.js
    from_latest_block.js
    wrong_args.js
    handle_errors.js
  events/
    ...

Despite the fact, that this is out-of-scope of this issue and we have a separate issue for it. I can see no reason why to not do it right now. It is faster than testing websockets manually.

Yeah, it makes sense. Would agree with you, that that will add an extra layer of testing from the client perspective

[franklywatson]

Looking good guys thanks! Maybe just a couple of nits left to address above?

If we speak about one small postman example with a simple request on a separate page - I don't mind

Yeah, for postman just one simple example would do. Then I can add an AWS example next to it @illia-malachyn

[Guitarheroua]

Looking good guys thanks! Maybe just a couple of nits left to address above?

If we speak about one small postman example with a simple request on a separate page - I don't mind

Yeah, for postman just one simple example would do. Then I can add an AWS example next to it @illia-malachyn

@franklywatson Done it. Added "Postman UI example" and "Common errors" pages.

[franklywatson]

Thanks guys, looks good @illia-malachyn @Guitarheroua . I think we're done here! Once we've released the functionality will merge this

[peterargue]

couple small comments, but otherwise this looks good.

one I think is a change we should make in the error handling implementation.

[jribbink]

Should this have a timestamp?

[Guitarheroua]

This endpoint does not have a timestamp in the gRPC version, and as we use the same functionality inside Websockets, this does not have it either. Should it be present? If yes, I could create an issue for this.

[jribbink]

Yeah, if we could add one here to synchronize with the data returned by the events topic, that would be awesome. Thanks @Guitarheroua

[illia-malachyn]

I opened an issue for this onflow/flow-go#7176

[jribbink]

Thank you!

[illia-malachyn]

@jribbink we'll probably postpone the implementation of this though. can u leave a comment in the issue explaining why it matters to you?

[jribbink]

It's not critical, it was just a suggestion so that consumers can have access to the same data through the account_statuses topic as they do through events (as all of the other data here is matching and these statuses are derived from events). But obviously if there's significant effort associated it's not necessary at all.

[treethought]

this does not match list_subscription in flow-go https://github.com/onflow/flow-go/blob/master/engine/access/rest/websockets/models/base_message.go#L6

[illia-malachyn]

thanks! Good catch!
I opened a PR onflow/flow-go#7317