Front-end JavaScript API for JSONbin.io {☁️}
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.
npm i jsonbin-io.js
or download file directly from GitHub
// 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
All methods in this library return promises
🔑 = feature that requires using a secret key
🔐 = parameter that requires using a secret key
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.
jsonbin.create(data[, collectionId[, name[, makePublic]]]);
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.
📬 string
ID of the created bin.
(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 a public bin
🔑 Read a private bin
jsonbin.read(id[, version]);
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".
📬 object
The data content of the bin.
(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);
}
})();
Crate a new version in a public bin
🔑 Create a new version in a private bin
jsonbin.update(id, data[, replaceLatest]);
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.
📬 integer
Version of the bin.
(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 a bin that was created with a secret key from your account
jsonbin.delete(id);
🔐 id
string
ID of the bin to delete.
📬 string
A message indicating that the bin has been deleted and the number of versions that it had.
// 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);
}
})();
🔑 Create a collection
jsonbin.c.create(name);
🔐 name
string
(Optional) Set the name of the collection. 3 to 32 characters.
📬 string
ID of the created collection.
(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 the name of a collection
jsonbin.c.update(id , name);
🔐 id
string
ID of the collection to update.
🔐 name
string
Set the new name of the collection. 3 to 32 characters.
📬 boolean
true
(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);
}
})();
These are part of the experimental API and are subject to change.
Get a list of the versions of a public bin
🔑 Get a list of the versions of a private bin
jsonbin.e.versions(id);
id
string
ID of the bin to query.
📬 object
Contains a count of bin versions and a list of versions with associated timestamps.
(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
}
Get geographical information about an IP address
jsonbin.g.lookup(address);
address
string
IPv4 or IPv6 address to query.
📬 object
Geographical properties associated to the reported location of the IP address.
(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
}
You can experiment and learn using this interactive CodePen example.