Paths and pointers

Most of the endpoints for interacting with Items have support for JSON path and JSON pointer expressions which allow you to dig into your data and fetch or update specific parts of an item's data.

This also works when fetching a list of items. You can fetch just the parts you need, which reduces the amount of data transferred and makes it easier to work with complex or deeply-nested data.

Let's imagine we have 3 items in a list (with path name sample-list), with the following data:

Item #1

{name: "Alice"
age: 30
locations: [0: {city: "New York"
state: "NY"
}
1: {city: "Los Angeles"
state: "CA"
}
]
}

Item #2

{name: "Bob"
age: 40
locations: [0: {city: "Chicago"
state: "IL"
}
1: {city: "Houston"
state: "TX"
}
]
}

Item #3

{name: "Claire"
age: 50
locations: [0: {city: "Phoenix"
state: "AZ"
}
1: {city: "Philadelphia"
state: "PA"
}
]
}

Let's try out some examples.

Fetch partial data

To fetch only the name field for a specific item:

123

curl https://api.jsonpad.io/lists/sample-list/items/568bd348-a7b7-4136-a9a8-cb5048537598/data/name \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

"Alice"

We could do a similar thing with a JSON Pointer expression if we wanted. For example, to fetch the name and age fields from the same item:

123

curl https://api.jsonpad.io/lists/sample-list/items/568bd348-a7b7-4136-a9a8-cb5048537598/data?path=$.[name,age] \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

[0: "Alice"
1: 30
]

We can fetch partial data from each item in the list like so:

123

curl https://api.jsonpad.io/lists/sample-list/items/data/name \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

[0: "Alice"
1: "Bob"
2: "Claire"
]

Here's another example using a JSON Pointer expression:

123

curl https://api.jsonpad.io/lists/sample-list/items/data?path=$.[name,age] \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

[0: [0: "Alice"
1: 30
]
1: [0: "Bob"
1: 40
]
2: [0: "Claire"
1: 50
]
]

Update partial data

Similarly to how we can fetch just a part of an item's data, we can use JSON Pointer expressions to create, replace, update, or patch part of an item's data.

123456

curl https://api.jsonpad.io/lists/sample-list/items/568bd348-a7b7-4136-a9a8-cb5048537598/data/locations/0 \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "population": 8097282
      }'

This will deep-merge the data at the specified path with the data in the request body, resulting in the following data:

{name: "Alice"
age: 30
locations: [0: {city: "New York"
state: "NY"
population: 8097282
}
1: {city: "Los Angeles"
state: "CA"
}
]
}

Delete partial data

We can use JSON Pointer expressions to delete part of an item's data like so:

1234

curl https://api.jsonpad.io/lists/sample-list/items/568bd348-a7b7-4136-a9a8-cb5048537598/data/locations/0 \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>"

This will result in the following data:

{name: "Alice"
age: 30
locations: [0: {city: "Los Angeles"
state: "CA"
}
]
}

2024-11-15