jsonbin-io.js v0.8.4
Front-end JavaScript API for JSONbin.io {☁️}
Table of Contents
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.jsor 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 dataEndpoints
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
📬 booleantrue
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.