Page: HTTP REST unichat endpoint
2019-11-21 11:11
HTTP REST Unichat Endpoint
Allows access to every unichat API method with a single HTTP JSON call on
POST https://chat.mainnetwork.io/api/<method_name>
Where <method_name>
is a name of the unichat API method to call, and
args
data parameter should contain any method arguments if any.
Use Content-Type: application/json
and the JSON encoding for parameters and
returned value.
call arguments must be passed as args
parameter, encoded with JSON. E.g
the request body should be like:
{"args":{"email":"....","password":"$$$$"}}
On success, it returns status: 'OK'
and whatever data API method returned:
{
status: 'OK',
// any data API method has returned
}
On error, the 400 result code will be returned and the data will contain following structure:
{status: "error", error_code: error_code, error_text: error_text}
The error_code
is a constant per-error string value that always same and
should be used by caller to react to the error. error_text
instead is a
varying description that is intended only to be read by human (user or developer)
but must not be used to interpret the error.
Specifying domain token
The application domain token should be specified in the request header
APP_DOMAIN_TOKEN
. The "test_token1" could be used for testing.
Authenticating user
Most API methods, as explained in unichat API, requires user authenticaion.
When loggin in with some login method, callint party gets the extended
`chat user record
, which includes auth_token
fields.
The application must then set the request header USER_AUTH_TOKEN
to this value
with each request that needs user authentication. Please note that you should
explicitely use this request header field, do not mistake it with other
authentication headers. Always use USER_AUTH_TOKEN
in api calls.
Logging out
Just clear the saved auth_token
value and do not add the header. Do not pass
this header with empty or improper value as it will cause error.
Receiving events
Events are available with SSE, see SSE server events article for details.
To subscribe to SSE, the client has to obtain the SSE authenitcation code using create_sse_auth_code()
call, see unichat API. With this code, subscribe to the SSE events with the
following URL: https://chat.mainnetwork.io/api/events?auth_code=<code>
, for example:
var evtSource = new EventSource("https://chat.mainnetwork.io/api/events?auth_code="+sse_token, { withCredentials: true } );
evtSource.addEventListener("unichat_notification", function(e) {
console.log("got notification: ");
console.log(e.data)
},false);
This code receives unichat API notifications in unichat_notification
events.
This is generally all the client software need.
Additionaly, application might find handy to process other SSE events the endpoint provides. Notice that to receive these special SSE events one need to add separate event listener, the listener in the sample above receives only unichat notifications.
event_source_ready
event
This event is send once per established connection, what means that after this event applicaiton will receive events stream.
ping
event
This event is sent periodically by the service to check the connection is not closed or lost. Application does not need to process it in any way.