Indexes

Indexes allow you to sort and filter items based on values inside each item's data.

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

Creating indexes

When creating a list (using the POST lists endpoint), you can include a indexes property containing an array of indexes to create.

Once the list has been created, any items that are added to the list or updated in the list will have their data indexed so that they can be filtered and sorted.

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.

Required fields

default_descending Whether or not this index will be sorted in descending order by default.
name The name for this index.
path The path to the property value indexed by this index, using JSON pointer format.
type The index value type. Possible values are:
  • number
  • string
  • boolean
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","indexes":[{"name":"testindex","path":"/testproperty","type":"string","default_descending":false}]}'

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

Index value types

The value type of an index affects how items will be sorted and filtered. The value of the property pointed to by the index must be of the specified type, otherwise the item's data will not be indexed.

string Values will be indexed as strings.
number Values will be indexed as numbers, and will be ordered numerically when sorted.
boolean Values will be indexed as 1 for true and 0 for false.

Reserved index names

Some words cannot be used as index names, as they would conflict with existing API parameter names. If you try to create an index using a reserved name, the API will respond with a 400 Bad Request status code. The following names are reserved:

  • page
  • page_size
  • sort
  • descending
  • timezone
  • callback
  • created
  • updated
  • index

Filtering items with indexes

To filter a list of items by an index, just include a parameter with the name of the index you want to filter by, where the parameter value is the value you want to filter by.

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

Sorting items with indexes

To sort a list of items by an index, just use the index name in the sort parameter.

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