[API]: Improve stream API doc-strings and UX

[candida-d]

API Overview

In order to improve the API experience for the streaming API We will improve the doc-strings so that they better describe what data they give, and how a user would manage updates So that users can fully understand how to build up local stores of the current state

Background: This started as a discussion in this slack thread: https://vegaprotocol.slack.com/archives/C02TG33SX41/p1710766821577549

where a reference to Binance documentation for how a user can use their API to build up a local state of the orderbook. We want a similar page in our Vega documentation but while investigating it became clear that the API doc for the market-depth streaming API are lacking any useful information.

For example we have two streaming API ObserveMarketsDepth and ObserveMarketDepthUpdate. The doc strings make it unclear what the difference between the two are. In fact the difference is that the first returns a full snapshot of the market depth for each update and the latter will only return the diffs at each update.

Task 1: Review all streaming API doc strings and give more information about what it returns, do they return the full state each time, or just updates? If it is just an update how would you merge it with the previous state (for example, on the orders stream order-ID and the version number of the order are useful fields help merge an update from the stream with what you already have)

It was noted by FE that the orders-stream API return an initial snapshot of the order book state before stream updates. Under the hood the data-node simply calls ListOrders() and sending the results down the stream before starting to send the updates. They said it was very useful.

// sendOrdersSnapshot literally just calls ListOrders()
if err := t.sendOrdersSnapshot(ctx, req, srv); err != nil {
		return formatE(err)
	}
ordersChan, ref := t.orderService.ObserveOrders(ctx, t.config.StreamRetries, req.MarketIds, req.PartyIds, ptr.UnBox(req.ExcludeLiquidity))

Task 2: We should do the same for the ObserveMarketDepthUpdate stream API. That way a user only needs to call a single API to build up a local orderbook state and start receiving updates.

Task 3: Make sure the market-depth API streams work. For example at the time of writing calling this on testnet:

curl -L -X GET 'https://api.n00.testnet.vega.rocks/api/v2/stream/markets/depth/updates'

returns no updates, despite the fact on console I can see the market depths changing all the time.

Questions

Open questions about the feature implementation, what can be done with the APIs, or currently unresolved questions around the feature.

See slack thread for more context.

Additional Details (optional)

Any additional information that provides context or gives information that will help us develop the feature.