2.3 RPC

The TeamWorks Real-time API supports RPC requests. Some of these RPC methods deal with managing the WebSocket session and others make changes in the TeamWorks system.

The RPC methods that make changes to the TeamWorks system are also available in the REST API. For example, both APIs provide the ability to comment on a topic. Because each REST request has overhead when establishing a connection and authenticating the user, the Real-time API is more efficient. However, the Real-time API does not duplicate all functionality available through REST. It only supports actions where the resulting efficiency and immediacy significantly improve the user experience.

Making an RPC request involves sending an RPC request message to the server. The server will process the request asynchronously and send an RPC response message sometime later. If a client sends multiple requests, the server makes no guarantee about the order of the response messages. The client must keep track of pending requests in order to match response messages with the original request message.

To help the client do this, the request and response messages include a request_id field. The server includes in the response whatever ID the client provided in the request message. As a best practice, the client should generate a unique ID for each request. These IDs need only be unique for the client session. Something as simple as a number sequence, i.e. 1, 2, 3, etc., is sufficient.

NOTE:If the request message is not well-formed JSON, or if it specifies an invalid value for an enumerated type (such as EventStream type), the server will be unable to parse the message. When this occurs, the server is not able to read the request_id or method fields and therefore does not include those fields in the response message.

2.3.1 Request Messages

{
   "message_type": "rpc_request",
   "method": "create_topic",
   "request_id": "12345abcde",
   "entity": {
      "@type": "topic",
      "room":{
         "id": "456"
      },
      "body": "Hi, everyone, here’s a new topic to discuss."
   }
}

2.3.2 Response Messages

{
   "message_type": "rpc_request",
   "method": "create_topic",
   "request_id": "12345abcde",
   "status": {
      "status_code": 200
   }
   "entity": {
      "@type": "topic",
      "room":{
         "id": "456"
      },
      "body": "Hi, everyone, here's a new topic to discuss."
   }
}

Status

The status object in the response message indicates whether the operation completely successfully. It contains a numeric status code, which is patterned after HTTP status codes.

Typical status codes are:

200 (Success)
400 (Bad request)
403 (Forbidden)
404 (Not found)
409 (Conflict)
500 (Internal server error)
503 (Service Unavailable)

NOTE:For status_code numbers greater than or equal to 300, the status object will also include additional information, for example:

"status": {
   "status_code": 404,
   "error": {
      "code": "ROOM_NOT_FOUND",
      "message": "No room exists with ID 234"
   }
}

For more information about possible error codes, see {list of error codes shared between the REST and real-time APIs in the doc}.

2.3.3 Methods

The following table shows the supported RPC methods. For more information about request and response entities, see the Data Types section of the REST API documentation.

Method	Request Entity Object	Response Entity Object	Description
create_comment	Comment	Comment	Add a comment to a topic or comment
create_topic	Topic	Topic	Post a new topic to a room.
delete_comment	Comment or String (comment HRef)	CommentReference	Delete a comment
delete_topic	Topic or String (topic HRef)	TopicReference	Delete a topic
get_format_preferences	None	FormatPreferences	Retrieve message formatting preferences
ping	None	None	Ping the server to test the validity of the web socket session
set_format_preferences	FormatPreferences	FormatPreferences	Update message formatting preferences
subscribe_to_stream	EventStream	EventStream	Subscribe to the specified stream
update_comment	Comment	Comment	Update a comment
update_topic	Topic	Topic	Update a topic
unsubscribe_from_stream	EventStream	EventStream	Unsubscribe from the specified stream