chainHead: Allow single connection calls and enforce order of events (#…

…137)

* chainHead: Allow single connection calls and clarify order of events

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* chainHead: Use shorter phrasing

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update src/api/chainHead_unstable_call.md

Co-authored-by: James Wilson <james@jsdw.me>

* Update src/api/chainHead_unstable_stopOperation.md

Co-authored-by: James Wilson <james@jsdw.me>

* Update src/api/chainHead_unstable_continue.md

Co-authored-by: James Wilson <james@jsdw.me>

* Update src/api/chainHead_unstable_body.md

Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

* Update src/api/chainHead_unstable_call.md

Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

* Update src/api/chainHead_unstable_storage.md

Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

* Extend the same connection to other rpc classes

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* chainHead: Remove mention of the connections from chainHead individual
methods

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* api: Ensure order of events in the API section

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Remove repetitive operation ID order mention

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update src/api.md

Co-authored-by: James Wilson <james@jsdw.me>

* Adjust calling RPC classes from the same connection

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Add generic single connection phrase

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

---------

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>
Co-authored-by: James Wilson <james@jsdw.me>
Co-authored-by: Pierre Krieger <pierre.krieger1708@gmail.com>

src/api.md

@@ -4,6 +4,10 @@ Note that all parameters are mandatory unless specified otherwise. All functions
 
 Any missing parameter, or parameter with an invalid format, should result in a JSON-RPC error being returned, as described in the JSON-RPC specification.
 
+Any function returning an opaque subscription or operation ID ensures that this is returned before any related notifications are generated.
+
+The functions within each respective category must be called from the same connection in order to work together.
+
 ## Glossary
 
 - "hexadecimal-encoded" designates a binary value encoded as hexadecimal. The value must either be empty, or start with `"0x"` and contain an even number of characters.