Home Docs
Join
Introduction Requests Responses Security and authentication Realtime Realtime responses GET lists GET lists/{name} GET items/{id} Filtering events Realtime errors Rate limiting Errors Timestamps Pagination Sorting JSONP callbacks Limitations Caching Parameters General API routes Lists Items Indexes Events

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.

Privacy Policy Contact © jsonpad 2018