jsonbin - A JSON store as a RESTful service

jsonbin(1)
json RESTful store
jsonbin(1)

NAME

jsonbin.org - A personal JSON store as a RESTful service

SYNOPSIS

curl https://jsonbin.org/remy/blog

Access

To save data, you'll first need to sign in to get an API key. All examples below use example as the username.

DESCRIPTION

jsonbin.org is a personal key/value JSON store as a service. Protected behind authentication and API key requests, data is stored as JSON and can be deep linked. A permissioning model also allows specific paths to your store to become public to share with others.

The aim of the project is to provide a simplified data store for tinkerers.

Important: jsonbin is currently in open beta. If you have questions, please get in touch.

Authentication

By default all user store data is protected behind auth either via browser sign in, or an authorization token. The token is your apikey. For example:

curl -X POST https://jsonbin.org/example/blog \
     -H 'authorization: token abcd-xyz-123' \
     -d '{ url: "https://remysharp.com" }'

To use jsonbin in the browser, it's recommended that you use a bearer token with a limited expiry:

fetch('https://jsonbin.org/me/urls', {
  headers: {
    // example uses 1 minute token restricted to `urls` path
    authorization: 'Bearer [token]',
  }
}).then(res => res.json()).then(res => {
  console.log(res);
});

Endpoints

A private namespace URL "_" is used for jsonbin specific endpoints:

/me Alias to your /example path.
/_/me Your full profile.
/_/me/apikey Your API key.
/_/me/apikey DELETE to revoke your current key.
/_/me/username Your username.
/_/me/public Your public paths.
/_/me/:path Deep link to profile properties.
/_/bearer(?exp=ms&path=…) Generate a bearer token (for client use)
/_/help This page.
/_/version Current jsonbin version.
/_/login Auth with github.
/_/logout Clear your session.

The following methods with your authorization header will access your data store:

GET return given path mapped to a JSON path.
POST store the payload (supports JSON and files).
PATCH merge the payload with the endpoint.
DELETE store path.

For example:

curl -X PATCH \
     -H 'authorization: token abcd-xyz-123' \
     -d'{ "topic": "code" }' \
     https://jsonbin.org/example/blog

By default all endpoints are private, but you can modify a specific entry point to be public by default by changing the permissions:

PUT /example/:path/_perms make the :path public.
DELETE /example/:path/_perms make :path private.
GET /example/:path/_perms check permissions of :path.

Public endpoints accept GET requests without the authorization header.

Notes on PATCH

The PATCH method implements the JSON Merge Patch standard (RFC 7396) when the target endpoint is an object. This means if you wish to remove a property from your store, a value of null is sent:

curl -X PATCH \
     -H 'authorization: token abcd-xyz-123' \
     -d'{ "title": null }' \
     https://jsonbin.org/example/blog

The exception is that when the endpoint is an array, a PATCH will always push onto the endpoint. If you need to reset the array you can POST to the endpoint, or you can DELETE an individual array element.

Example storing files

You can use jsonbin as a shared clipboard across machines. Creating an alias to upload STDIN via curl could be posted to a public URL:

alias jsonbin="curl -X 'POST' \
      -H'authorization: token abcd-xyz-123' \
      -F'content=@-' \
      https://jsonbin.org/example/clipboard"
echo "foo" | jsonbin

Example with arrays

As well as objects, arrays are also supported. To delete an array element, it should be accessed using the index as per:

curl -X DELETE https://jsonbin.org/example/urls/1

To push a new element, so long as the endpoint contains an array:

curl -X PATCH https://jsonbin.org/example/urls \
     -d "foo.com"

BUGS

This project lives at jsonbin. Please report bugs to jsonbin/issues.

AUTHOR

Remy Sharp <remy@leftlogic.com>

January 2017
jsonbin(1)