JsonBank Documentation

Appearance

Python SDK ​

github | pypi

The official Python client for JsonBank. Requires Python 3.9+.

Installation ​

shell
pip install jsonbank

Initialize ​

JsonBank can be initialized with or without api keys.
Api Keys are only required when you want to access private/secured documents

python
from jsonbank import JsonBank

jsb = JsonBank()
python
from jsonbank import JsonBank

# Initialize with Api keys.
jsb = JsonBank(
    public_key="JSB_PUBLIC_KEY",
    private_key="JSB_PRIVATE_KEY",
)

# authenticate the api keys
jsb.authenticate()

Public Api Key ​

A read-only key. Use it to authenticate() and to read your own private documents. Public documents need no key at all.

Private Api Key ​

A write-only key, only needed to create, update or delete documents.

Check Authentication ​

To check if the user is authenticated, use the is_authenticated method.
Make sure to have called authenticate method before.

python
jsb.authenticate()

# check if the user is authenticated
jsb.is_authenticated()  # True

Public Content Methods ​

Public contents do not require authentication.

get_document_meta() ​

Get a public document meta details either by id or path. Does not return the content of the document. To get the content, use get_content method.

python
meta = jsb.get_document_meta("jsonbank/sdk-test/index.json")
# meta is a DocumentMeta object
print(meta.id)            # id of the document
print(meta.project)       # project name
print(meta.name)          # name of the document
print(meta.content_size)  # size of the document
print(meta.path)          # path of the document
print(meta.updated_at)    # last update time
print(meta.created_at)    # creation time
python
@dataclass
class DocumentMeta:
    id: str
    project: str
    path: str
    name: str
    content_size: ContentSize
    created_at: str
    updated_at: str
    folder_id: Optional[str] = None

@dataclass
class ContentSize:
    number: int
    string: str

get_content() ​

Get a public document content either by id or path. It returns the parsed json (a dict or list).

python
data = jsb.get_content("jsonbank/sdk-test/index.json")
print(data["author"])  # jsonbank
json
{
  "name": "JsonBank SDK Test File",
  "author": "jsonbank"
}

get_content_as_string() ​

Get a public document content either by id or path as a string. It returns the raw json string.

python
data = jsb.get_content_as_string("jsonbank/sdk-test/index.json")
# data is a string

get_github_content() ​

Grab a public json file from Github. This will read from the default branch of the repo.
It returns the parsed json.

Note: Referenced file must be a public json file.
python
data = jsb.get_github_content("org/repo/file.json")

# example
result = jsb.get_github_content("jsonbankio/documentation/github-test.json")

get_github_content_as_string() ​

Same as get_github_content but returns the content as a string.

Note: Referenced file must be a public json file.
python
data = jsb.get_github_content_as_string("org/repo/file.json")

# example
result = jsb.get_github_content_as_string("jsonbankio/documentation/github-test.json")

Access Own Content ​

Your own content is the documents in your projects. To read them, initialize with your api keys and authenticate first. See With Api Keys for more details.

Note: These methods need your public api key. Call authenticate() before using them.

get_own_content() ​

Get one of your documents either by id or path. Works for private documents too. It returns the parsed json.

python
data = jsb.get_own_content("sdk-test/index.json")
# data is a dict (or list)

get_own_content_as_string() ​

Same as get_own_content but returns the raw json string.

python
data = jsb.get_own_content_as_string("sdk-test/index.json")
# data is a string

get_own_document_meta() ​

Get the meta of one of your documents either by id or path. Returns the same DocumentMeta as get_document_meta.

python
meta = jsb.get_own_document_meta("sdk-test/index.json")

has_own_document() ​

Check if one of your documents exists, either by id or path.

python
jsb.has_own_document("sdk-test/index.json")  # True
jsb.has_own_document("does-not-exist")       # False
Note: Returns False instead of raising when the document is not found.

Managing Content ​

Create, update and delete documents in your projects.

Note: These methods need your private api key.

create_document() ​

Create a new document in a project. folder is optional, leave it out to create at the project root. content can be a dict, list, or a json string.

python
doc = jsb.create_document(
    name="new_doc.json",
    project="sdk-test",
    folder="folder",  # optional
    content={"name": "new_doc", "author": "jsonbank"},
)
python
@dataclass
class NewDocument:
    id: str
    name: str
    path: str
    project: str
    created_at: str
    exists: bool = False

create_document_if_not_exists() ​

Same as create_document, but if the document already exists it is fetched and returned instead of raising.

python
doc = jsb.create_document_if_not_exists(
    name="index.json",
    project="sdk-test",
    content={"name": "JsonBank SDK Test File", "author": "jsonbank"},
)

# when it already existed
doc.exists  # True

update_own_document() ​

Update the content of one of your documents either by id or path. content can be a dict, list, or a json string.

python
result = jsb.update_own_document("sdk-test/index.json", {
    "name": "JsonBank SDK Test File",
    "author": "jsonbank",
    "updated": True,
})

result.changed  # True
python
@dataclass
class UpdatedDocument:
    changed: bool

delete_document() ​

Delete one of your documents either by id or path.

python
jsb.delete_document("sdk-test/folder/new_doc.json")
# -> DeletedDocument(deleted=True)
Note: Returns deleted=False instead of raising when the document is not found.

Folders ​

Group documents into folders inside a project.

get_folder() ​

Get a folder either by id or path.

python
folder = jsb.get_folder("sdk-test/folder")
python
@dataclass
class Folder:
    id: str
    name: str
    path: str
    project: str
    created_at: str
    updated_at: str
    stats: Optional[FolderStats] = None

@dataclass
class FolderStats:
    documents: int
    folders: int

get_folder_with_stats() ​

Same as get_folder but also fills in stats (how many documents and folders are inside).

python
folder = jsb.get_folder_with_stats("sdk-test/folder")

print(folder.stats.documents)
print(folder.stats.folders)

create_folder() ​

Create a new folder in a project. folder is optional, use it to nest inside another folder.

python
folder = jsb.create_folder(
    name="folder",
    project="sdk-test",
)

create_folder_if_not_exists() ​

Same as create_folder, but if the folder already exists it is fetched and returned instead of raising.

python
folder = jsb.create_folder_if_not_exists(
    name="folder",
    project="sdk-test",
)

# when it already existed
folder.exists  # True

Uploading Files ​

Upload a json file straight from your file system.

upload_document() ​

Reads a file from disk and creates a document from it. name and folder are optional, name defaults to the file name.

python
doc = jsb.upload_document(
    file_path="./upload.json",
    project="sdk-test",
    folder="folder",  # optional
)
python
@dataclass
class NewDocument:
    id: str
    name: str
    path: str
    project: str
    created_at: str
    exists: bool = False

Error Handling ​

Methods raise a JsonBankError when something goes wrong. It has a code you can check.

python
from jsonbank import JsonBankError

try:
    jsb.create_folder(name="folder", project="sdk-test")
except JsonBankError as e:
    if e.code == "name.exists":
        # folder already exists, ignore it or fetch it instead
        pass
    else:
        raise

Common error codes:

  • notFound — the document or folder does not exist.
  • name.exists — a document or folder with that name already exists.
Note: Some methods don't raise, they return a value instead: has_own_document() returns False, delete_document() returns deleted=False, and the ..._if_not_exists() methods return the existing item with exists=True.

Next steps ​