API audit (docs Vs API implementation)

[gordsport]

Issue

It has been noticed that the API documentation is not always easy to follow. This issue is to start the investigation/audit into the API docs and spawn off issues / tasks to ensure that all documentation is correct and up-to-date.

Users of the APIs must be able to reference the documentation and have clear information with good working examples (where applicable).

Tasks (subject to change post review):

• [x] Review API docs and ensure that the docs matches the implementation (examples work etc..)
• [x] Ensure we have docs about all subscriptions or WebSockets
• [x] Break down the tasks into issues to be prioritised

Additional information:

• https://vegaprotocol.slack.com/archives/C02TG33SX41/p1676582988570099

Examples of WebSocket API docs:

• https://vegaprotocol.slack.com/archives/C02TG33SX41/p1676641031929559

When picking up this work we should ensure that we coordinate with the docs team.

Also related to:

• https://github.com/vegaprotocol/vega/issues/7108

[wwestgarth]

Audit complete. Tickets identified have been created and labelled as api-cleanup. Websockets docs is almost complete and being handled under another ticket.