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 its 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.