Realtime
The Realtime API provides instant updates when lists and items are created, modified or deleted. This is done with Long Polling.
To get instant updates when information changes, you will need to open a connection to the realtime API, including your username and realtime token as HTTP basic auth credentials. If the connection is successful, a response will be received when a matching event occurs.
You can generate a realtime token on the Account page.
The realtime token can only be used to read data, and will only work when used in realtime API requests; it cannot be used to modify items or lists in your account.
Additionally, only lists that have the realtime_enabled property set to true will send events.
The realtime API's base URL is http://realtime.jsonpad.io.
Realtime responses
All data received from the realtime API is in JSON format, including errors.
When an event occurs (for example, when an Item is updated) that matches a currently open connection, the realtime API will respond with a 200 OK status code and the response body will contain information about the event and the affected resource.
Example response
{
"object_id": 23928779684449152,
"event_type": "item-update",
"event_data": {
"created": "2015-03-14T23:08:15+00:00",
"data": {
// Item data...
},
"id": "23928779684449152",
"updated": "2015-03-14T23:08:15+00:00"
}
}
Requests will timeout after 30 seconds, after which you should re-connect to the realtime API in order to continue receiving updates. If a connection times out, the realtime API will respond with a 200 OK status code and the event_type property in the response body will be set to timeout.
Example response
{
"object_id": null,
"event_type": "timeout",
"event_data": null
}
GET lists
The lists path can be used to receive events that occur on any list in your account.
Example request $ curl http://realtime.jsonpad.io/lists \ -u username:realtimetoken
Events
The following events will generate a realtime API response when using the lists path.
list-create | A list was created. The created list will be included in the event_data property in the response body. |
list-update | A list was renamed. The updated list will be included in the event_data property in the response body. |
list-delete | A list was deleted. The event_data property in the response body will be set to null. |
list-delete-all | All lists under your account were deleted. Both the object_id and the event_data properties in the response body will be set to null. |
GET lists/{name}
The lists/{name} path can be used to receive events that occur on a specific list in your account. This includes events that occur on items in the specified list.
Example request $ curl http://realtime.jsonpad.io/lists/testlist \ -u username:realtimetoken
Events
The following events will generate a realtime API response when using the lists/{name} path.
list-update | The list was renamed. The updated list will be included in the event_data property in the response body. |
list-delete | The list was deleted. The event_data property in the response body will be set to null. |
list-delete-all | All lists under your account were deleted. Both the object_id and the event_data properties in the response body will be set to null. |
item-create | An item was added to the list. The created item will be included in the event_data property in the response body, and the object_id property will be set to the created item's id. |
item-update | An item in the list was updated. The updated item will be included in the event_data property in the response body, and the object_id property will be set to the updated item's id. |
item-delete | An item in the list was deleted. The event_data property in the response body will be set to null, and the object_id property will be set to the deleted item's id. |
item-delete-all | All items in the list were deleted. The event_data property in the response body will be set to null, and the object_id property will be set to the list's name. |
GET items/{id}
The items/{id} path can be used to receive events that occur on a specific item.
Example request $ curl http://realtime.jsonpad.io/items/23928779684449152 \ -u username:realtimetoken
Events
The following events will generate a realtime API response when using the items/{id} path.
list-delete | The list in which the item is stored was deleted. The event_data property in the response body will be set to null and the object_id property will be set to the deleted list's name. |
list-delete-all | All lists under your account were deleted. Both the object_id and the event_data properties in the response body will be set to null. |
item-update | The item was updated. The updated item will be included in the event_data property in the response body. |
item-delete | The item was deleted. The event_data property in the response body will be set to null. |
item-delete-all | All items in the item's list were deleted. The event_data property in the response body will be set to null, and the object_id property will be set to the list's name. |
Filtering events
It is possible to listen for specific events by setting the events parameter when connecting to the realtime API.
This parameter takes a comma-separated list of event names. Valid event names are:
- list-create
- list-update
- list-delete
- list-delete-all
- item-create
- item-update
- item-delete
- item-delete-all
Example request $ curl http://realtime.jsonpad.io/lists?events=list-update,list-delete \ -u username:realtimetoken
Realtime errors
If an error occurs while connecting to the realtime API, the API will respond with a status code in the 400 or 500 range. The response body will contain information about the error that occurred, using the same format as jsonpad API errors.
See Realtime error codes for a list of possible error codes returned by the realtime API.