Introduction
Welcome to the Open Basin API! You can use our API to access the Open Basin endpoints, which enables your users to access their data in your applications.
We have language bindings in Shell, JavaScripts, and Swift! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Get Started
To setup configuration, use this code:
// basin.js
import { initializeApp } from "open-basin";
const config = {
network: "MUMBAI",
provider: {
id: ${PROVIDER_ID},
address: ${PROVIDER_ADDRESS},
key: ${API_KEY}
}
}
const basin = initializeApp(config);
export default basin;
// AppDelegate.swift
import OpenBasin
Basin.configure(for: .mumbai,
id: ${PROVIDER_ID},
address: ${PROVIDER_ADDRESS},
key: ${API_KEY})
# With shell, you can just pass the correct headers and
# parameters with each request.
curl "api.openbasin.io/*" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}"
Make sure to replace
${}
with the proper values.
Open Basin uses API keys, Public Addresses, and IDs to allow access to the API. You can register for new Open Basin keys at our developer portal.
Open Basin expects for the API key to be included in the header and the Address and ID in the parameters of all API requests to the server that looks like the following:
Authorization: ${API_KEY}
provider_address: ${PROVIDER_ID}
provider_id: ${PROVIDER_ADDRESS}
How It Works
Open Basin is a structured data lake that anyone can read or write to. All stored data has owner(s) that control access to it. As an open system, any provider can request access to any set of data. Once an owner(s) grants a provider permission, the provider can interact with the data as instructed by its owner(s).
The System
All data on Open Basin is stored on IPFS and structured on Ethereum. When writing to Open Basin the process is as follows:
- HTTPS POST with data, standard, bucket, and owner(s).
- If the provider has permissions, Open Basin validates the data against the provided standard and bucket.
- The data is encrypted and stored in IPFS.
- The IPFS address is encrypted and stored on the Open Basin Ethereum ledger.
Glossary
Term | Description |
---|---|
Owner | Has complete control over their data by providing and revoking permissions to their data. |
Provider | Reads and writes data on behalf of the owners. Providers can only work with data as the owners see fit. |
Standard | Valid JSON Schema to enforce a specified data structure. When storing data on Open Basin, all data must be validated against its corresponding standard. |
Bucket | A set of validated data where owners pool data of the same type or category. Buckets enforce specified data standards so providers can expect a consistent structure. |
Document | A wrapper object for the data stored on the ledger that contains document metadata and raw data. |
Authentication
Using User Profile as example:
In order to interact with data on Open Basin, owners must allow you to do so.
Request Permissions
import basin from './basin.js';
await basin.auth.request.bucket("public_profiles", "${OWNER_ADDRESS}");v
import OpenBasin
Basin.auth
.request
.owner("${OWNER_ADDRESS}")
.bucket(in: "public_profiles") { result in
switch result {
case .success(let permissions):
print(permissions)
case .error(let error):
print(error)
}
}
Permission methods are note supported via Shell
The above command returns JSON structured like below:
{
"status": bool
}
Requests access to an owner's data in a specified bucket.
The user will be directed to an Open Basin web page to execute the authorization.
Parameters
Parameter | Description |
---|---|
owner | The address of the owner |
bucket | The id of the bucket |
provider_address | The address of the requestor |
Check Permissions
import basin from './basin.js';
const permitted = await basin.auth.permissions.bucket("public_profiles", "${OWNER_ADDRESS}");
console.log(permitted);
import OpenBasin
Basin.auth
.permissions
.owner("${OWNER_ADDRESS}")
.bucket(in: "public_profiles") { result in
switch result {
case .success(let permissions):
print(permissions)
case .error(let error):
print(error)
}
}
curl "api.openbasin.io/datastore/standards/all/standards" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}" \
-d owner: "${OWNER_ADDRESS}" \
-d bucket: "public_profiles"
The above command returns JSON structured like below:
{
"status": bool
}
Checks if the requesting provider has permissions to an owner's data in a specified bucket.
HTTP Request
GET api.openbasin.io/datastore/auth/bucket/permissions
Parameters
Parameter | Description |
---|---|
owner | The address of the owner |
bucket | The id of the bucket |
provider_address | The address of the requestor |
Standards
Standards are a valid JSON schema that enforces structure and format of data.
Properties
id: string
- A unique identifier
minter: address
- The address of the provider that minted the standard
name: string
- The name of the standard
timestamp: date
- The date and time at which the standard was minted
schema: JSON Schema
- The schema used to validate data against
Mint Standards
import basin from './basin.js';
await basin.mint.standard(
"profile_v0",
"profile",
{
"$schema": "http://json-schema.org/draft-06/schema#",
"$ref": "#/definitions/profile_v0",
"definitions": {
"profile_v0": {
"type": "object",
"additionalProperties": {},
"properties": {
"name": {
"type": "string"
},
"image": {
"type": "string"
}
},
"required": [
"name",
"image"
],
"title": "profile_v0",
"description": "Your core prfile data."
}
}
}
);
import OpenBasin
Basin.mint.standard(id: "profile_v0",
name: "profile",
schema: [
"$schema": "http://json-schema.org/draft-06/schema#",
"$ref": "#/definitions/profile_v0",
"definitions": [
"profile_v0": [
"type": "object",
"additionalProperties": [:],
"properties": [
"name": [
"type": "string"
],
"image": [
"type": "string"
]
],
"required": [
"name",
"image"
],
"title": "profile_v0",
"description": "Your core profile data."
]
]
])
{ result in
switch result {
case .success(let response)
print(response)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/standard/mint" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}" \
-d id: "profile_v0" \
-d name: "profile" \
-d schema: {
"id": "profile_v0",
"name": "profile",
"schema": {
"$schema": "http://json-schema.org/draft-06/schema#",
"$ref": "#/definitions/profile_v0",
"definitions": {
"profile_v0": {
"type": "object",
"additionalProperties": {},
"properties": {
"name": {
"type": "string"
},
"image": {
"type": "string"
}
},
"required": [
"name",
"image"
],
"title": "profile_v0",
"description": "Your core prfile data."
}
}
}
}
The above command returns JSON structured like below:
{
"status": "success"
}
Creates a Standard and stores on Open Basin
HTTP Request
POST api.openbasin.io/datastore/standard/mint
Query Parameters
Parameter | Description |
---|---|
id | The ID of the standard to mint |
name | The name of the standard |
schema | The JSON schema of the standard |
Get Standards
import basin from './basin.js';
const standards = await basin.api.standards.all.get();
console.log(standards);
import OpenBasin
Basin.api.standards.getAllStandards { result in
switch result {
case .success(let standards)
print(standards)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/standards/all/standards" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}"
The above command returns JSON structured like below:
[
{
"standard": {
"id": string,
"minter": address,
"name": string,
"schema": any,
"timestamp": date,
"token": number
},
"standard_id": string
}
]
This endpoint retrieves all standards.
HTTP Request
GET api.openbasin.io/datastore/standards/all/standards
Query Parameters
No additional parameters
Get a Specific Standard
import basin from './basin.js';
const standard = await basin.api.standard("profile_v0").get();
console.log(standard)
import OpenBasin
Basin.api.standard("profile_v0").getStandard { result in
switch result {
case .success(let standard)
print(standard)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/standard" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}"\
-d provider_address: "${PROVIDER_ADDRESS}" \
-d id: "profile_v0"
The above command returns JSON structured like this:
{
"id": string,
"minter": address,
"name": string,
"schema": any,
"timestamp": date,
"token": number
}
This endpoint retrieves a specific Standard.
HTTP Request
GET api.openbasin.io/datastore/standard
Query Parameters
Parameter | Description |
---|---|
id | The ID of the standard to retrieve |
Buckets
Buckets are sets of data that conform to a set of whitelisted standards and serve the same purpose.
Properties
id: string
- A unique identifier
minter: address
- The address of the provider that minted the bucket
name: string
- The name of the bucket
description: string
- The description of the data the bucket holds
timestamp: date
- The date and time at which the bucket was minted
allowed_standards: string[]
- The set of whitelisted standards that the bucket dat must conform to
Mint Bucket
import basin from './basin.js';
await basin.mint.bucket(
"public_profiles",
"Your Profiles",
"Your public profile to be used on other apps."
["profile_v0"]
);
import OpenBasin
Basin.mint.bucket(id: "public_profiles",
name: "Your Profiles",
description: "Your public profile to be used on other apps.",
standards: ["profile_v0"]) { result in
switch result {
case .success(let response)
print(response)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/bucket/mint" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}" \
-d id: "public_profiles" \
-d name: "Your Profiles" \
-d description: "Your public profile to be used on other apps." \
-d standards: ["profile_v0"]
The above command returns JSON structured like below:
{
"status": "success"
}
Creates a Bucket and stores on Open Basin
HTTP Request
POST api.openbasin.io/datastore/bucket/mint
Query Parameters
Parameter | Description |
---|---|
id | The ID of the bucket to mint |
name | The name of the bucket |
description | The description of the bucket |
allowed_standards | The list of whitelisted standards for the bucket |
Update Bucket Standards
import basin from './basin.js';
await basin.mint.appendStandard(
"public_profiles",
"profile_v1"
);
import OpenBasin
Basin.mint.appendStandard(to: "public_profiles",
standard: "profile_v1") { result in
switch result {
case .success(let response)
print(response)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/bucket/standard/append" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}" \
-d bucket: "public_profiles" \
-d standard: "profile_v1"
The above command returns JSON structured like below:
{
"status": "success"
}
Appends a new standard to the bucket's standard whitelist.
HTTP Request
POST api.openbasin.io/datastore/bucket/standard/append
Query Parameters
Parameter | Description |
---|---|
bucket | The ID of the bucket to update |
standard | The standard to append |
Get Buckets
import basin from './basin.js';
const buckets = await basin.api.buckets.all.get();
console.log(buckets);
import OpenBasin
Basin.api.buckets.getAll { result in
switch result {
case .success(let buckets)
print(buckets)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/buckets/all" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}"
The above command returns JSON structured like below:
[
{
"standard": {
"id": string,
"minter": address,
"name": string,
"description": string,
"timestamp": date,
"allowed_standards": string[]
},
"standard_id": string
}
]
This endpoint retrieves all buckets
HTTP Request
GET api.openbasin.io/datastore/buckets/all
Query Parameters
No additional parameters
Get a Specific Bucket
import basin from './basin.js';
const bucket = await basin.api.bucket("public_profiles").get();
console.log(bucket)
import OpenBasin
Basin.api.bucket("public_profiles").getBucket { result in
switch result {
case .success(let bucket)
print(bucket)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/bucket" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}"\
-d provider_address: "${PROVIDER_ADDRESS}" \
-d id: "public_profiles"
The above command returns JSON structured like this:
{
"id": string,
"minter": address,
"name": string,
"description": string,
"timestamp": date,
"allowed_standards": string[]
}
This endpoint retrieves a specific bucket.
HTTP Request
GET api.openbasin.io/datastore/bucket
Query Parameters
Parameter | Description |
---|---|
id | The ID of the bucket to retrieve |
Documents
Documents are wrapper objects for raw data to hold the metadata of the data. They are stored within buckets and conform to a specified standard
Properties
token: number
- The token index of the document within its bucket
owners: address[]
- The set of owners of the document
standard: string
- The standard id that the data conforms to
bucket: string
- The bucket id that the document is stored in
timestamp: date
- The date and time at which the document was minted
data: JSON
- THe raw data of the document
Mint Document
import basin from './basin.js';
await basin.mint.document(
["${OWNER_ADDRESS}"],
"public_profiles",
"profile_v0",
{
"name": "Drillbit Taylor",
"image": "https://tiny.one/emmet"
}
);
import OpenBasin
Basin.mint
.document(owners: ["${OWNER_ADDRESS}"],
bucket: "public_profiles",
standard: "profile_v0",
data: [
"name": "Drillbit Taylor",
"image": "https://tiny.one/emmet"
]) { result in
switch result {
case .success(let response)
print(response)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/document/mint" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}" \
-d owners: ["${OWNER_ADDRESS}"] \
-d bucket: "public_profiles" \
-d standard: "profile_v0" \
-d data: {
"name": "Drillbit Taylor",
"image": "https://tiny.one/emmet"
}
The above command returns JSON structured like below:
{
"status": "success"
}
Creates a Document and stores on Open Basin
HTTP Request
POST api.openbasin.io/datastore/document/mint
Query Parameters
Parameter | Description |
---|---|
bucket | The id of the document's bucket |
standard | The id of the document's standard |
owners | The list of owners of the document |
data | The raw JSON to store |
Update Document
import basin from './basin.js';
await basin.mint.updateDocument(
"public_profiles",
0,
"profile_v0",
{
"name": "Alamo Taylor",
"image": "https://tiny.one/emmet"
}
);
import OpenBasin
Basin.mint
.updateDocument(bucket: "public_profiles",
document: 0,
standard: "profile_v0",
data: [
"name": "Alamo Taylor"
"image": "https://tiny.one/emmet"
]) { result in
switch result {
case .success(let response)
print(response)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/document/update" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}" \
-d bucket: "public_profiles" \
-d standard: "profile_v0" \
-d document: "0"
-d data: {
"name": "Alamo Taylor",
"image": "https://tiny.one/emmet"
}
The above command returns JSON structured like below:
{
"status": "success"
}
Updates the raw value of the document
HTTP Request
POST api.openbasin.io/datastore/document/update
Query Parameters
Parameter | Description |
---|---|
document | The token of the document |
bucket | The id of the document's bucket |
standard | The id of the document's standard |
data | The raw JSON to replace the current data |
Get Owner Documents in Bucket
import basin from './basin.js';
const documents = await basin.api.bucket("public_profiles").owner("${OWNER_ADDRESS}").documents();
console.log(documents)
import OpenBasin
Basin.api.bucket("public_profiles").owner("${OWNER_ADDRESS}").getDocuments { result in
switch result {
case .success(let documents)
print(documents)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/bucket/owner/documents" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}" \
-d provider_address: "${PROVIDER_ADDRESS}" \
-d owner: "${OWNER_ADDRESS}" \
-d bucket: "public_profiles"
The above command returns JSON structured like this:
[
"document": {
"token": number,
"bucket": address,
"standard": string,
"owners": address[],
"timestamp": date,
"data": JSON
},
"document_token": number
]
Retrieves all documents in a bucket owner by a specific address
HTTP Request
GET api.openbasin.io/datastore/bucket/owner/document
Query Parameters
Parameter | Description |
---|---|
owner | The address of the owner |
bucket | The id of the specified bucket |
Get Specific Document
import basin from './basin.js';
const document = await basin.api.bucket("public_profiles").document(0).get();
console.log(document)
import OpenBasin
Basin.api.bucket("public_profiles").document(0).getDocument { result in
switch result {
case .success(let document)
print(document)
case .error(let error)
print(error)
}
}
curl "api.openbasin.io/datastore/document" \
-H Authorization: "Bearer ${API_KEY}" \
-d provider_id: "${PROVIDER_ID}"\
-d provider_address: "${PROVIDER_ADDRESS}" \
-d token: "0" \
-d bucket: "public_profiles"
The above command returns JSON structured like this:
{
"token": number,
"bucket": address,
"standard": string,
"owners": address[],
"timestamp": date,
"data": JSON
}
Updates the raw value of the document
HTTP Request
GET api.openbasin.io/datastore/document
Query Parameters
Parameter | Description |
---|---|
token | The token of the document |
bucket | The id of the document's bucket |
Errors
The Open Basin API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The data requested is hidden for administrators only. |
404 | Not Found -- The specified data could not be found. |
405 | Method Not Allowed -- You tried to access data with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The data requested has been removed from our servers. |
429 | Too Many Requests -- You're requesting too much data! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |