Transports
DocsTransports
WebSocket
One socket that carries any call by name, several at once, with the same JSON as REST.
Shape
wss://api.inorbit.hr/v1/ws is one connection for every route in the reference,
addressed by the RPC's full name instead of a path. Frames are JSON text, one object
each. The token goes on the upgrade request as Authorization: Bearer.
From the client:
| Frame | Meaning |
|---|---|
{"type":"call","id":"1","method":"tbd.<service>.v1.<Service>/<Method>","body":{…}} | start a call; body may be omitted for an empty request |
{"type":"cancel","id":"1"} | stop a call in flight |
To the client:
| Frame | Meaning |
|---|---|
{"type":"data","id":"1","body":{…}} | one answer; a unary call sends exactly one, a stream sends many |
{"type":"end","id":"1"} | the call is over and the id is free again |
{"type":"error","id":"1","code":…,"error":…,"details":[…]} | the call failed; the error envelope with the id it belongs to |
{"type":"error","code":…,"error":…,"details":[…]} | the frame itself was refused; no call is named and the socket stays open |
{"type":"call","id":"1","method":"tbd.accounts.v1.AccountsService/GetMe"}
{"type":"data","id":"1","body":{"…":"…"}}
{"type":"end","id":"1"}The method name is the operationId of the operation in the reference, with the
service's package in front: Service.Method in the document is
tbd.<backend>.v1.Service/Method on the socket. The whole request message is the
frame's body; path and query rules belong to REST and do not apply here.
Rules
idis yours, unique among the calls you have in flight, free again afterendorerror. Every call ends with exactly one of the two, cancellation included.- Calls are independent: a unary call answers while streams stay open. A refusal never closes the socket.
- At most 64 calls in flight per connection; the 65th is
rate_limiteduntil one ends. - A frame from the client is at most 256 KiB.
- A client that reads slowly stalls only its own calls; frames wait in one bounded queue per connection.
- The gateway gives the socket no timeout.