Talking to the API
You can interact directly with the API using any progamming language or platform capable of making HTTP requests, or you can use client libraries (SDKs) which make it even easier to integrate jsonpad.io into your projects. Right now there's only a Javascript SDK, but more are on the way!
In this guide, we'll go over how to interact directly with the API, what to send and what to expect in responses. Check out Using the SDKs for information on downloading, installing, and using the SDKs.
cURL
cURL is a command-line tool for making HTTP requests. It's available on most operating systems and is a great way to test API endpoints.
Here's an example of how you can use cURL to create a new list on jsonpad.io:
curl https://api.jsonpad.io/lists \
-H "Content-Type: application/json" \
-H "x-api-token: <YOUR TOKEN>" \
-d '{
"name": "My New List",
"description": "This is a new list",
"pathName": "my-new-list",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name"]
},
"pinned": false,
"readonly": false,
"realtime": true,
"protected": false,
"indexable": true,
"activated": true
}'Some things to note:
- The
-Hflag is used to set headers. In this case, we're setting theContent-Typeandx-api-tokenheaders. - The
Content-Typeheader should always be set to"application/json". - Every request to the API must include an
x-api-tokenheader, set to one of your Token values. See Token permissions for more information on creating tokens and managing permissions. - The
-dflag is used to send data in the request body. In this case, we're sending JSON data for creating a list. - You can use the
-Xflag to specify the HTTP method. For example,-X POSTwould make a POST request. If you don't specify a method, cURL will default to GET, unless you're sending data in the request body, in which case it will default to POST. We've skipped this flag in the example because we're making a POST request and it includes a request body (note the-dflag), so it'll usePOSTby default.
Node.js (fetch API, Axios, etc.)
When you're integrating jsonpad.io into a Node.js project, you can either interact with the API directly using an HTTP client, or if there's an SDK available for your chosen language / platform, you can use that.
Check out Using the SDKs for information on downloading, installing, and using the SDKs.
If you prefer to use an HTTP client, here are some examples using popular clients:
<script>
// This will create an item in the "tasks" list
fetch(
'https://api.jsonpad.io/lists/tasks/items',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-token': '<YOUR TOKEN>',
},
body: JSON.stringify({
title: 'Mow the lawn',
completed: false,
}),
}
)
.then(response => response.json())
.then(data => console.log(data));
</script>HTTP methods
The API supports the following HTTP methods for interacting with lists, items, and indexes:
GETWe use this method for endpoints which return data, without modifying it in any way. For example, fetching an item or viewing all of the items in a list.POSTWe use this method for creating new resources. For example, adding a new item to a list.
It's also used in some cases for updating an item. In this case it means we're sending some data which will be merged with the existing data, rather than replacing it entirely.
PUTWe use this method for updating an entire resource. For example, updating an item's data, or modifying a list or index.
When updating an item using a
PUTendpoint, we will replace the existing data with the data you provide in the request body.PATCHWe use this method for making partial updates to an item's data using JSON Patch syntax.DELETEWe use this method for deleting resources. For example, deleting an item from a list, or deleting an entire list.
When you delete a list, this will delete indexes attached to the list and all of the items in the list.
You can switch on list protection to prevent accidental deletion of lists if they contain any items.
Rate limits
Most API endpoints have rate limits applied to them. The exact limits will depend on your subscription plan.
If you exceed the rate limit for an endpoint, you'll receive a 429 Too Many Requests response. The response will include headers with further information.
retry-after60The number of seconds to wait before making another request.x-rate-limit-total600The total number of requests made in the current 60-second period.x-rate-limit-remaining599The number of requests remaining in the current 60-second period before hitting the rate limit.
Caching
The API supports caching of resources using the ETags and Last-Modified dates. This can be useful if you want to cache lists, items, or indexes locally in your app in order to reduce the number of requests made to the API.
ETags
ETags are only available for items. When you create, update, or fetch an item, the API will return an ETag in an etag response header.
Then, when you fetch an item from the API, you can include the ETag inside the if-none-match request header, and if the item's data matches the ETag, the API will return a 304 Not Modified response, indicating that the data hasn't changed since you last fetched it. Additionally, the request will not count towards your rate limit.
If the data has changed, the API will return the item as usual, along with a new ETag.
Last-modified
Last modified dates are available for lists, items, and indexes. When you fetch a resource from the API, the API will include a last-modified header in the response containing the date that the resource was last updated, in ISO 8601 format.
Then, when you fetch the same resource again, you can include an ISO 8601 date inside the if-modified-since request header, and if the resource hasn't been updated since this date, the API will return a 304 Not Modified response. Additionally, the request will not count towards your rate limit.