Lists

Items are stored in lists. This allows you to organise and separate your data according to your application's requirements.

Lists can have a schema, which will ensure that the items in the list all follow a particular data format. List schemas use the JSON schema format. See List schemas for further information.

{
	"created": "2015-03-14T23:08:15+00:00",
	"has_schema": true,
	"index_count": 0,
	"item_count": 0,
	"data_size": 0,
	"name": "testlist",
	"realtime_enabled": false,
	"updated": "2015-03-14T23:08:15+00:00"
}

List fields

created The time that this list was created.
has_schema A boolean value indicating if this list has a JSON schema.
index_count The number of indexes for this list.
item_count The number of items contained in this list.
data_size The total data size for all items in this list, measured in bytes.
name The unique name for this list.
realtime_enabled A value indicating if realtime events are enabled or disabled for this list and it's contents.
updated The time that this list was last updated. This time is updated both when the list's name is changed and when an item in the list is added, removed or updated. If the list has not been updated, this will be the same as the time that the list was created.

Sorting lists

Default name
descending: false
name Sort lists by name.
item_count Sort lists by the number of items contained in the list.
data_size Sort lists by the total data size for all items contained in the list.
created Sort lists by their created time.
updated Sort lists by their last updated time.

List schemas

List schemas can be used to set constraints on the data format for items contained in the list. The list schema should use JSON schema format.

To create a list with a schema, just include a schema property in the list's data when creating the list.

Once a list with a schema has been created, the schema cannot be updated or removed. If you want to update or remove a schema, you will have to create a new list and move the existing list's items across manually.

Example request
$ curl https://jsonpad.io/api/v1.0/lists \
	-u username:token \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{"name":"testlist","schema":{"title":"Test Schema","type":"object"}}'

When creating or updating an item inside a list that has a schema, the item's data will be validated against the schema. If the data cannot be validated, the API will respond with a 400 Bad Request status code. The response body will include a validation_errors property containing an array of messages.

{
	"status_code": 400,
	"error_code": 3023,
	"message": "Couldn't create item: the data failed to validate against the list schema",
	"validation_errors": [
		{
			"path": "/testproperty1",
			"message": "Invalid type: string"
		},
		{
			"path": "/testproperty2",
			"message": "Array is too short (must have at least 3 items)"
		},
		{
			"path": "/testproperty2",
			"message": "Array items must be unique (items 0 and 1)"
		}
	]
}

List indexes

List indexes allow item data to be indexed so that items can be sorted and filtered. See Indexes for further information.

Once a list with indexes has been created, the indexes cannot be updated or removed. If you want to update or remove an index, you will have to create a new list and move the existing list's items across manually.

List routes

GET lists

Return a list of lists.

Example request
$ curl https://jsonpad.io/api/v1.0/lists \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	"descending": false,
	"lists": [
		{
			"created": "2015-03-14T23:08:15+00:00",
			"has_schema": false,
			"index_count": 0,
			"item_count": 0,
			"data_size": 0,
			"name": "testlist",
			"realtime_enabled": false,
			"updated": "2015-03-14T23:08:15+00:00"
		},
		// Lists continued...
	],
	"page": 1,
	"page_size": 50,
	"pages": 10,
	"sort": "name",
	"total": 510
}

GET lists/{name}

Return the specified list.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	"list": {
		"created": "2015-03-14T23:08:15+00:00",
		"has_schema": false,
		"index_count": 0,
		"item_count": 0,
		"data_size": 0,
		"name": "testlist",
		"realtime_enabled": false,
		"updated": "2015-03-14T23:08:15+00:00"
	}
}

GET lists/{name}/events

Return a list of events for the specified list.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/events \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	"descending": true,
	"events": [
		{
			"action": "Create",
			"data": {
				"details": "List created.",
				"list_name": "testlist"
			},
			"id": "23928779684449151",
			"object_id": "23928779684449150",
			"object_type": "List",
			"time": "2015-03-14T23:08:15+00:00"
		},
		// Events continued...
	],
	"page": 1,
	"page_size": 50,
	"pages": 1,
	"sort": "time",
	"total": 3
}

GET lists/{name}/schema

Return the schema for the specified list.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/schema \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	// Schema data
}

GET lists/{name}/indexes

Return a list of indexes for the specified list.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/indexes \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	"indexes": [
		{
			"default_descending": false,
			"name": "testindex",
			"path": "/testproperty",
			"type": "number"
		},
		// Indexes continued...
	],
	"total": 3
}

GET lists/{name}/indexes/{name}

Return the specified index from the specified list.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/indexes/testindex \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	"default_descending": false,
	"name": "testindex",
	"path": "/testproperty",
	"type": "number"
}

POST lists

Create a new list.

Required fields

name The list name. This must be unique; you cannot have multiple lists with the same name.

Optional fields

schema A JSON schema using the format defined here. If a schema is provided, it will be used to validate items that are added to the list or modified in the list.
indexes An array of indexes for this list. See Indexes for further information.
realtime_enabled A value indicating if realtime events should be enabled or disabled for this list.
Example request
$ curl https://jsonpad.io/api/v1.0/lists \
	-u username:token \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{"name":"testlist","realtime_enabled":true}'

Example response
{
	"list": {
		"created": "2015-03-14T23:08:15+00:00",
		"has_schema": false,
		"index_count": 0,
		"item_count": 0,
		"data_size": 0,
		"name": "testlist",
		"realtime_enabled": true,
		"updated": "2015-03-14T23:08:15+00:00",
	}
}

PUT lists/{name}

Rename the specified list.

Required fields

name The list's new name. This must be unique; you cannot have multiple lists with the same name.

Optional fields

realtime_enabled A value indicating if realtime events should be enabled or disabled for this list.
Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist \
	-u username:token \
	-X PUT \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{"name":"testlist2"}'

Example response
{
	"list": {
		"created": "2015-03-14T23:08:15+00:00",
		"has_schema": false,
		"index_count": 0,
		"item_count": 0,
		"data_size": 0,
		"name": "testlist2",
		"realtime_enabled": false,
		"updated": "2015-03-14T23:12:32+00:00"
	}
}

DELETE lists/{name}

Delete the specified list and all items contained in the list.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist \
	-u username:token \
	-X DELETE \
	-H "Accept: application/json"

This endpoint will return a 204 No Content status code and the response body will be empty.

DELETE lists

Delete all lists and items that belong to the authenticated user.

Example request
$ curl https://jsonpad.io/api/v1.0/lists \
	-u username:token \
	-X DELETE \
	-H "Accept: application/json"

This endpoint will return a 204 No Content status code and the response body will be empty.