1

Create a free account so that you can start storing and managing JSON data.

2

First, let's create a list for storing JSON items.

Here's the data we'll be using for the list:

{
	"name": "people",
	"indexes": [
		{
			"name": "age",
			"default_descending": true,
			"path": "/age",
			"type": "number"
		},
		{
			"name": "country",
			"default_descending": false,
			"path": "/address/country",
			"type": "string"
		}
	]
}

And here's the request you'll need to send to create the list:

$ curl https://jsonpad.io/api/v1.0/lists \
	-u username:token \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{"name":"people","indexes":[{"name":"age","default_descending":true,"path":"/age","type":"number"},{"name":"country","default_descending":false,"path":"/address/country","type":"string"}]}'

You have now created a list called people. It has a couple of indexes (called age and country), which will help with sorting and filtering the list's contents. More on this later.

3

Next, we'll add some items to the list.

Here's an example of an item that we want to add:

{
	"first_name": "Alice",
	"last_name": "Baker",
	"age": 28,
	"address": {
		"city": "New York",
		"country": "USA"
	}
}

Here are some requests for adding items to the list we just created:

$ curl https://jsonpad.io/api/v1.0/lists/people/items \
	-u username:token \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{"first_name":"Alice","last_name":"Baker","age":28,"address":{"city":"New York","country":"USA"}}'

$ curl https://jsonpad.io/api/v1.0/lists/people/items \
	-u username:token \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{"first_name":"Chris","last_name":"Davis","age":23,"address":{"city":"Edinburgh","country":"Scotland"}}'

$ curl https://jsonpad.io/api/v1.0/lists/people/items \
	-u username:token \
	-X POST \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{"first_name":"Elise","last_name":"Fremont","age":35,"address":{"city":"Paris","country":"France"}}'

Your list should now contain 3 items. We'll check this in the next step.

4

Now, let's get a look at the items that we just added to the list.

Here's a request to view the list's contents:

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

The response should look something like this:

{
    "items": [
        {
            "id": "24009806222196752",
            "data": {
                "first_name": "Alice",
                "last_name": "Baker",
                "age": 28,
                "address": {
                    "city": "New York",
                    "country": "USA"
                }
            },
            "created": "2015-05-13T20:24:56+00:00",
            "updated": "2015-05-13T20:24:56+00:00"
        },
        {
            "id": "24009806222196754",
            "data": {
                "first_name": "Chris",
                "last_name": "Davis",
                "age": 23,
                "address": {
                    "city": "Edinburgh",
                    "country": "Scotland"
                }
            },
            "created": "2015-05-13T20:26:22+00:00",
            "updated": "2015-05-13T20:26:22+00:00"
        },
        {
            "id": "24009806222196756",
            "data": {
                "first_name": "Elise",
                "last_name": "Fremont",
                "age": 35,
                "address": {
                    "city": "Paris",
                    "country": "France"
                }
            },
            "created": "2015-05-13T20:26:31+00:00",
            "updated": "2015-05-13T20:26:31+00:00"
        }
    ],
    "total": 3,
    "sort": "index",
    "descending": false,
    "page": 1,
    "pages": 1,
    "page_size": 50
}

Ok, great! Looks like all of the items are in the list. You'll notice that each item now has an id field - this can be used to get a specific item from the list, like so:

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

The response for this request should be:

{
    "item": {
        "id": "24009806222196752",
        "data": {
            "first_name": "Alice",
            "last_name": "Baker",
            "age": 28,
            "address": {
                "city": "New York",
                "country": "USA"
            }
        },
        "created": "2015-05-13T20:24:56+00:00",
        "updated": "2015-05-13T20:24:56+00:00"
    }
}
5

There are various ways to sort or filter the items in a list. Below are a few example requests that you might want to try out.

To get a specific page of results, try setting the page parameter, like so:

$ curl https://jsonpad.io/api/v1.0/lists/people/items?page_size=2&page=2 \
	-u username:token \
	-H "Accept: application/json"

For this request, we've set the page_size parameter as well. By default, lists will return up to 50 items, however you can set this value anywhere between 1 and 100.

You can also sort items in a list by their created date or updated date, for example:

$ curl https://jsonpad.io/api/v1.0/lists/people/items?sort=created&descending=1 \
	-u username:token \
	-H "Accept: application/json"

Note that we also set the descending parameter to sort items by their created date, from new to old.

Now, remember that we created some indexes for this list? This allows you to sort items based on specific values inside each item's data. Just use the index name in the sort parameter. For example, one of the indexes we created was called age. Let's try sorting the list using that index:

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

Indexes also allow us to filter items. Just use the index name as a parameter and set the parameter value to whatever you want to filter by. For example, if we only wanted to view people whose country is France, we would send this request:

$ curl https://jsonpad.io/api/v1.0/lists/people/items?country=france \
	-u username:token \
	-H "Accept: application/json"
6

Ok, so let's say you want to get the items from a list, but you only want to see each item's data. You can do this by adding /data to the request path:

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

The response for this request should be:

[
    {
        "first_name": "Alice",
        "last_name": "Baker",
        "age": 28,
        "address": {
            "city": "New York",
            "country": "USA"
        }
    },
    {
        "first_name": "Chris",
        "last_name": "Davis",
        "age": 23,
        "address": {
            "city": "Edinburgh",
            "country": "Scotland"
        }
    },
    {
        "first_name": "Elise",
        "last_name": "Fremont",
        "age": 35,
        "address": {
            "city": "Paris",
            "country": "France"
        }
    }
]

You can also do this for a specific item in the list, like so:

$ curl https://jsonpad.io/api/v1.0/lists/people/items/24009806222196752/data \
	-u username:token \
	-H "Accept: application/json"

The response for this request should be:

{
    "first_name": "Alice",
    "last_name": "Baker",
    "age": 28,
    "address": {
        "city": "New York",
        "country": "USA"
    }
}

It's also possible to dig right into an item's data and get a particular value. For example, to get the city for a particular person, we'd send this request:

$ curl https://jsonpad.io/api/v1.0/lists/people/items/24009806222196752/data/address/city \
	-u username:token \
	-H "Accept: application/json"

The response should look like:

"New York"

You can also do this for every item in a list, like so:

$ curl https://jsonpad.io/api/v1.0/lists/people/items/data/address/city \
	-u username:token \
	-H "Accept: application/json"

The response should look like:

[
    "New York",
    "Edinburgh",
    "Paris"
]

This method of using pointers straight into an item's data also works with POST, PUT and DELETE requests. See the documentation for detailed information.

7

So, that's the basics of how to use jsonpad. The API does loads more as well, so be sure to check the documentation for further information!