The Paperflow API exposes a WebSocket endpoint to allow a consumer to subscribe to and listen for changes to specific resources. The WebSocket is exposed at /v1/websocket and is subject to the same authorization constraints and methods as any other endpoint.
It is important to note that the current version of the WebSocket endpoint only allows a user to listen for changes and does not have commands for creating and updating resources via the WebSocket. This has to be done via the respected endpoints for each resource.
Data transmission
The WebSocket uses UTF-8 encoded JSON for all messages. All messages are furthermore required to be JSON object of the following structure:
{
"type": "<message type>",
[any additional message data]
}
Requests and responses
The following message types can be transmitted from the client:
request
A command is sent from the client, with the following basic structure:
{ "type": "request",
"command": "<command name>",
"state": "<opaque client side reference for the request, such as a sequence number>",
"data": <request data> }
It is optional to pass a state, but it can be very helpful for tracking request/response relationships for a client.
response
A response from the server will be sent to the client, with the following basic structure:
{
"type": "response",
"status": "<response status>",
"state": "<opaque client side reference for the request the server is responding to>",
"data": <response data>
}
Note that a response does not always contain any data and that the state is only present if it was parseable from the client request.
The status can be one of:
-
success - The request was successful.
-
parse_error - The server failed to parse the client message.
-
invalid_type - The provided message type is not valid.
-
invalid_command - The provided command is not valid.
The client will now receive notifications whenever a particular resource is either updated or deleted. Please see the subscribe section for further details
Notifications
A notification from the server, likely due to a subscription by the client, with the following basic structure:
{
"type": "notification",
"event": "<event>",
"data": <notification data>
}
The event can be one of:
resource_changed
The resource was changed. Data will contain the new resource ex data:
{"type":"voucher","id":5,"organization_id":1,"uploaded_by_user_id":1,...}
resource_deleted
The resource was deleted. Data will the id of the resource and the type ex data: {"id":5,"type":"voucher"}.
Commands
The WebSocket endpoint currently supports 2 different commands; subscribe andunsubscribe:
Subscribe
To subscribe to notifications about changes to one or more resources, the client issues a subscribe request with the data being a list of resources:
{
"type": "request",
"state": "<opaque client side reference for the command>",
"command": "subscribe",
"data": [
{
"type": "<resource type>",
"id": <ID>
},
[..]
]
}
If successful, the server will respond with a successful response:
{
"type": "response",
"state": "<same opaque client side reference as provided in the command>",
"status": "success",
"data": [
{
"type": "<resource type>",
"id": <ID>,
"status": <optional error code>
},
[..]
]
}
The status for a given resource can be one of the:
subscribed -The client was successfully subscribed to the resource.
not_found - The resource was not found.
After this, the client will receive the following notification event types:
resource_changed
Emitted when a resource the client has subscribed to is changed. The data of notification contains the data of the resource.
resource_deleted
Emitted when a resource the client has subscribed to is deleted. The data of the notification contains the type and ID of the resource.
Important: Subsequent to the response, the server will emit resource_changed notifications for the resources providing the state at the time of subscription to allow the client to be certain it has the latest state.
Available resource types:
The following resource types are supported:
-
voucher - Listen to changes on a particular voucher
-
file_posting - Listen to changes on a particular file posting
-
user -Listen to changes on a particular user
-
organization - Listen to changes on a particular organization
-
organization_status - Listen to changes on a particular organization’s vouchers
Example:
The following example shows how you can subscribe to the voucher with ID 5
request
{
"type": "request",
"state": "1",
"command": "subscribe",
"data": [
{
"type": "voucher",
"id": 5
}
]
}
response
{
"type": "response",
"state": "1",
"status": "success",
"data": [
{
"type": "voucher",
"id": 5,
"status": "subscribed"
}
]
}
Immediately after a subscription has been established the endpoint will emit a resource_changed notification so the client always has the current version of the resource:
{
"type": "notification",
"event": "resource_changed",
"data": [
{
"type": "voucher",
"id": 5,
"organization_id":1,
"status":"queued",
"edited":null,
"edited_in_web_app":null,
"edited_in_affiliate":null,
"edited_in_hdr":null
}
]
}
When the voucher resource is updated the client will receive a resource_changed or resource_deleted event as soon as it happens with the appropriate data.
Unsubscribe
To unsubscribe from notifications about changes to one or more resources, the client issues an unsubscribe request with data analogous to that of the subscribe request:
{
"state": "<opaque client side reference for the command>",
"command": "unsubscribe",
"data": [
{
"type": "<resource type>",
"id": <ID>
},
[..]
]
}
To prevent excessive error handling, the server always responds with success even if the user is not subscribed to the provided resources.
Available resource types:
The following resource types are supported:
-
voucher - Unsubscribe to changes on a particular voucher
-
file_posting - Unsubscribe to changes on a particular file posting
-
user - Unsubscribe to changes on a particular user
-
organization - Unsubscribe to changes in a particular organization
-
organization_status - Unsubscribe to changes on a particular organization’s vouchers
Example:
The following example shows how you can unsubscribe to the file posting with ID 2
request
{
"type": "request",
"state": "1",
"command": "unsubscribe",
"data": [
{
"type": "file_posting",
"id": 2
}
]
}
{
"type": "response",
"state": "1",
"status": "success"
}
Comments
0 comments
Please sign in to leave a comment.