Websocket API Reference
The websocket API works by passing messages from the client to the server and from the server to the client.
Messages accepted by the server
Currently, only one message type is accepted by the server. The message should be a JSON string in the following form:
{
"action" : "post-workitem",
"data" : <workitem>,
"headers" : <key_value_pairs>,
"conversationId" : <conversation identifier>
}
“headers” and “conversationId” are optional. Also see the section about authentication below.
- <workitem> is the same as the request body of POST workitems API.
- <key_value_pairs> are any headers that you would normally pass to POST workitems API. Content-Type is always assumed to be application/json, so it does not need to be passed.
- <conversation identifier> is a string that satisfies the regular expression ^[w]{1,40}$. This id is passed back to the caller in response messages and it is not interpreted by the system in any way. This is useful in situations where multiple requests are in flight therefore responses need to be disambiguated.
Authentication
Clients can authenticate in 2 ways:
- Using “Authorization” header with a bearer token in the initial websocket connect request. Websocket APIs in browsers do not allow this.
- Using “Authorization” header with a bearer token in the first “post-workitem” message. This works for both browser and other clients.
Example
The following example message is a post-workitem request with authentication. It uses the simplest possible workitem: it references an activity that has no inputs or outputs and does nothing.
{
"headers": {"Authorization" : "Bearer secret..." },
"action" : "post-workitem",
"data" : {
"activityId" : "Autodesk.Nop+Latest"
}
}
Messages sent by the server
Messages sent by the server are either JSON of the form below or error strings.
{
"action" = <action>
"data" = <data>
}
The table below lists the possible <action> values with their corresponding <data>.
action | data | example | Comment |
---|---|---|---|
error | string |
} |
Sent when an error is encountered during workitem processing. |
status | same as response body of GET workitems/:id |
} |
Sent when the workitem is accepted and when the workitem is completed. |
progress | same as payload of OnProgress. |
} |
May be sent 0 or more times as the workitem progresses. |
The sequence of messages sent by the server for a successful workitem submission are as follows:
- Exactly one (“initial status”):
{"action":"status", "data":{"status":"pending" ...}}
- Zero or more:
{"action":"progress", "data":{}}
- Exactly one (“final status”):
{"action":"status", "data":{"status":"success" ...}}
Note that other messages are possible in the future. Clients should follow an algorithm similar to the following:
- Submit WorkItem and wait for next message.
- If message is anything else but initial status indicating “pending” then error out.
- Wait for final status message ignoring other messages (or optionally using progress messages to inform the user about the progress of the workitem).