Front-end JavaScript API for JSONbin.io {☁️}

Table of Contents

• Get your API secret key
• Download
• Use
• Endpoints
  • Bins
    • Create
    • Read
    • Update
    • Delete
  • Collections
    • Create
    • Update
  • Experimental
    • Versions
  • Geolocation
    • Lookup
• CodePen Demo

Get your API secret key

A secret key is not required in order to use the core functionality of JSONbin.io. However, one is needed in order to create private bins, and to use more features of the API. You can get one at https://jsonbin.io/api-keys.

Download

npm i jsonbin-io.js

or download file directly from GitHub

Use

// Import the class from module
import JSONbin from './node_modules/jsonbin-io.js/src/jsonbin-io.js';

// Initialize an object from the imported class
const jsonbinPrivate = new JSONbin(🔑); // Secret key: private data and more features
const jsonbinPublic = new JSONbin(); // No secret key: only interact with public data

Endpoints

Full API Reference

All methods in this library return promises

🔑 = feature that requires using a secret key
🔐 = parameter that requires using a secret key

Bins

Create

Create a public bin

🔑 Create a private bin (or—optionally—a public bin) and link it to your account

⚠️ Bins created without a secret key are public and cannot be deleted.

Syntax

jsonbin.create(data[, collectionId[, name[, makePublic]]]);

Parameters

data object
The data content of the bin—will be passed to JSON.stringify().

🔐 collectionId string or null
(Optional) To add the bin to a collection that you created, set the ID of that collection.

🔐 name string or null
(Optional) Set the name of the bin. 128-character max length.

🔐 makePublic boolean
(Optional) When using a secret key, bins are created private by default. Set to true to make the bin public.

Return value

📬 string
ID of the created bin.

Example

(async () => {
  const data = {a: 1, b: 2, c: ['dogs', 'cats', 'motorcycles']};
  try {
    const id = await jsonbin.create(data);
    console.log(id); //-> '5c4cc6e7a1021c254834adab'
  }
  catch (err) {
    console.error(err.message);
  }
})();

Read

Read a public bin

🔑 Read a private bin

Syntax

jsonbin.read(id[, version]);

Parameters

id string
ID of the bin to read.

version integer
(Optional) Version of the bin to read. Set to 0 to get the original version. Defaults to "latest".

Return value

📬 object
The data content of the bin.

Example

(async () => {
  const id = '5c4cc6e7a1021c254834adab';
  try {
    const data = await jsonbin.read(id, 0);
    console.log(data); //-> '{"c":["dogs","cats","motorcycles"],"b":2,"a":1}'
  }
  catch (err) {
    console.error(err.message);
  }
})();

Update

Crate a new version in a public bin

🔑 Create a new version in a private bin

Syntax

jsonbin.update(id, data[, replaceLatest]);

Parameters

id string
ID of the bin to update.

data object
The data content of the bin—will be passed to JSON.stringify().

🔐 replaceLatest boolean
(Optional, Private bins only) Set to true to replace the content of the latest version of the bin instead of creating a new version.

Return value

📬 integer
Version of the bin.

Example

(async () => {
  const id = '5c4cc6e7a1021c254834adab';
  const newData = [1, 2, 'dogs', 'cats', 'motorcycles'];
  try {
    const version = await jsonbin.update(id, newData);
    console.log(version); //-> 1
    console.log(await jsonbin.read(id, version)); //-> '[1,2,"dogs","cats","motorcycles"]'
  }
  catch (err) {
    console.error(err.message);
  }
})();

Delete

🔑 Delete a bin that was created with a secret key from your account

Syntax

jsonbin.delete(id);

Parameters

🔐 id string
ID of the bin to delete.

Return value

📬 string
A message indicating that the bin has been deleted and the number of versions that it had.

Example

// Won't work without secret key

import JSONbin from './node_modules/jsonbin-io.js/src/jsonbin-io.js';
const jsonbin = new JSONbin(); // No secret key

(async () => {
  const id = '5c4cc6e7a1021c254834adab';
  try {
    const message = await jsonbin.delete(id); // An error is thrown here, so control is passed to the next catch block
    console.log(message);
  }
  catch (err) {
    console.error(err.message); //-> 'Error 401: Need to provide a secret-key to DELETE bins'
  }
  try {
    console.log(await jsonbin.read(id)); //-> '[1,2,"dogs","cats","motorcycles"]'
  }
  catch (err) {
    console.error(err.message);
  }
})();

// Works!

import JSONbin from './node_modules/jsonbin-io.js/src/jsonbin-io.js';
const jsonbin = new JSONbin(🔑); // Secret key

(async () => {
  const data = {a: 1, b: 2, c: [3, 4, 5]};
  try {
    const id = await jsonbin.create(data);
    console.log(id); //-> 5c4ce1de5bc16725808d4056
    const version = await jsonbin.update(id, data.c);
    console.log(version); //-> 1

    const msg = await jsonbin.delete(id);
    console.log(msg); //-> "Bin 5c4ce1de5bc16725808d4056 is deleted successfully. 1 versions removed."
  }
  catch (err) {
    console.error(err.message);
  }
})();

Collections

Create

🔑 Create a collection

Syntax

jsonbin.c.create(name);

Parameters

🔐 name string
(Optional) Set the name of the collection. 3 to 32 characters.

Return value

📬 string
ID of the created collection.

Example

(async () => {
  const name = 'My secret bins';
  try {
    const id = await jsonbin.c.create(name);
    console.log(id); //-> YOUR_COLLECTION_ID
  }
  catch (err) {
    console.error(err.message);
  }
})();

Update

🔑 Update the name of a collection

Syntax

jsonbin.c.update(id , name);

Parameters

🔐 id string
ID of the collection to update.

🔐 name string
Set the new name of the collection. 3 to 32 characters.

Return value

📬 boolean
true

Example

(async () => {
  const id = YOUR_COLLECTION_ID;
  const name = 'My public bins';
  try {
    const success = await jsonbin.c.update(id, name);
    console.log(success ? 'Great!' : 'Oh, no!'); //-> 'Great!'
  }
  catch (err) {
    console.error(err.message);
  }
})();

Experimental

These are part of the experimental API and are subject to change.

Versions

Get a list of the versions of a public bin

🔑 Get a list of the versions of a private bin

Syntax

jsonbin.e.versions(id);

Parameters

id string
ID of the bin to query.

Return value

📬 object
Contains a count of bin versions and a list of versions with associated timestamps.

Example

(async () => {
  const id = '5c4cc6e7a1021c254834adab';
  try {
    const versions = await jsonbin.e.versions(id);
    console.log(versions); //-> (See next code block for formatted output 👇)
  }
  catch (err) {
    console.error(err.message);
  }
})();

// Formatted console output:

{
  "binVersions": [
    {
      "version": 2,
      "created": "2019-01-27T04:22:55.847Z"
    },
    {
      "version": 1,
      "created": "2019-01-26T21:00:55.558Z"
    }
  ],
  "versionCount": 2,
  "success": true
}

Geolocation

Lookup

Get geographical information about an IP address

Syntax

jsonbin.g.lookup(address);

Parameters

address string
IPv4 or IPv6 address to query.

Return value

📬 object
Geographical properties associated to the reported location of the IP address.

Example

(async () => {
  const address = '199.59.149.165';
  try {
    const features = await jsonbin.g.lookup(address);
    console.log(features); //-> (See next code block for formatted output 👇)
  }
  catch (err) {
    console.error(err.message);
  }
})();

// Formatted console output:

{
  "range": [
    3342570496,
    3342571519
  ],
  "country": "US",
  "region": "NA",
  "eu": "0",
  "timezone": "America/Los_Angeles",
  "city": "San Francisco",
  "ll": [
    37.7758,
    -122.4128
  ],
  "metro": 807,
  "area": 1000
}

CodePen Demo

You can experiment and learn using this interactive CodePen example.