Concept

Overview

Singlebase is essentially Backend-as-a-Service (Baas) that operates via HTTP API calls.

Upon creating an account

Request

A request to Singlebase's API requires a secure HTTP API endpoint, API-Key, Bearer Auth Token and a JSON payload in CQL format, which will be sent via POST call to the API Endpoint.

HTTP is commonly associated with REST, which uses "resources" as its core concept. In contrast, Singlebase conceptual model is an entity object. As a result, entities in Singlebase are not identified by URLs. Instead, Singlebase operates on a single URL/endpoint, and all requests for a given service are directed at this endpoint.

API Endpoint

The endpoint is a secure URL that is provided by Singlebase to query and manipulate the data in your project.

https://cloud.singlebaseapis.com/api

Method and Content-Type

All requests must be sent via POST to the API endpoint and must have the content-type header as application/json, and include a JSON-encoded body.

HTTP Method: POST

Content-Type: application/json

API-KEY

An API-KEY is a unique string that is provided by Singlebase to access your project's backend when making API calls.

Do not share your API-KEY with anyone.

X-API-KEY: <API_KEY>

Secure Your API-Key

API-Key gives access to your project's data. Make sure you keep them secured and you don't share or use them inappriately.

SinglebaseCloud provides 3 types of API-KEY:

Frontend API-Key: To use for your frontend/client application, like React, Vue, Nextjs etc. This key has limited Read and Write access. Some operations may require users to be authenticated.
Backend API-Key: This key has limited Read and Write access, but with more priviledge. It's to be used in backend/server application like Python, Node, Golang. DO NOT USE THIS API-KEY ON THE FRONTEND.
Admin API-Key: This key has full Read and Write access to all of your data. DO USE SHARE THIS API-KEY ON THE FRONTEND - DO NOT SHARE THIS API-KEY WITH ANYONE.

Bearer Auth Token

Bearer Auth (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name "Bearer Authentication" can be understood as "give access to the bearer of this token." The bearer token is a JWT string, generated by Singlebase in response to a user's login request. The client must send this token in the Authorization header when making requests to protected resources:

Authorization: Bearer <JWT_TOKEN>

Payload

All payload must have an action and the defining object data.

{
  action: "",
}

Response

TDB

Response Status

Rate Limit

A rate limit is a set of rules that determine how many API calls an organization can make in a specified time period. The API rate limit is determined by the Organization Plan. The default API limit for trial account is 50 calls per minute and 1000 calls per hour.

Pagination

Common Query Language

Overview

Singlebase's Common Query Language / CQL is a Data Query & Manipulate Language to query and modify data, simply written in JSON format. Making it very easy to be used by any languages and frameworks.

Every CQL requires an action property and be sent via POST call to the Singlebase's API endpoint.

CQL provides a single way to

Example

//--- Request 
{
  action: "db.insert",
  collection: "articles",
  data: [
    {
      title: "Hello World",
      content: "This is a long content...",
      views: 0,
      ...
    }
  ]
}

//--- Response
{
  data: [
    {
      _key: "chipekj24te4lkr24ui0",
      _created_at: "2023-01-01",
      _modified_at: null,
      title: "Hello World",
      content: "This is a long content...",
      views: 0,
      ...
    }
  ]
}

//--- Request
{
  action: "auth.signup",
  email: "you@email.com",
  password: "myPassword1234",
  display_name: "Singlebase Cloud"
}

//--- Request
{
  action: "storage.get",
  _key: "chipekj24te4lkr24uig",
  url_signed: true
}

JSON Schema

Captcha

Security

This section describes the authentication and access control security features used in Singlebase.

Singlebase’s security design makes it easy to query your databases from any network-connected context, including a web browser. Connections to the database are secured using HTTPS. Authentication and access control are implemented using HTTP bearer tokens in the request header for each query.

To use these security models, Singlebase provides these resources:

Secrets: Each secret is an opaque bearer token, associated with a token document or key document within Singlebase, that provides access to a specific database. A secret is displayed only once at creation time; it should be stored securely, and needs to be revoked and recreated if lost.

Attribute-based access control (ABAC): ABAC roles define specific privileges, for query execution, to specific member identities within the database. Such roles provide fine-grained access control, and can modify the query behavior based on document attributes or time of day.

Tokens: A token grants authorized access to an associated identity. The actual permissions available are controlled with attribute-based access control (ABAC). The metadata for a token, including its hashed secret, is stored as a document in the internal tokens collection. Tokens are typically created using the Login function, which involves a credential that the identity knows, but can also be created directly for password-less identity-based authentication.

JSON Web Tokens (JWTs): A JWT grants authorized access to an associated identity that is managed by an external identity provider. The actual permission available are controlled with attribute-based access control (ABAC). A JWT is created when a user successfully authenticates with an external identity provider. Once a Singlebase database has been configured to accept JWTs for specific identity providers, a JWT can then be used to query Singlebase.

Keys: A key grants anonymous authorized access. The actual permissions granted are controlled with roles, which can be one a four built-in roles, or a user-defined attribute-based access control (ABAC) role. The metadata for a Key, including its hashed secret, is stored as a document in the system keys collection.

Captcha

Query Languages

To query and manipulate data in your project, Singlebase provides a **Common Query Language

written in JSON format, along with DocsQL docsql.md to get your data from the Datastore in a SQL like query.

CQL

CQL Example

{
    action: "db.fetch",
    collection: "articles",
    fields: ["_key", "title"],
    matches: {
        "categories:$includes": "blog"
    },
    limit: 20,
    
}

X-SQL

X-SQL is a powerful Documents Query Language which closely resembles traditional SQL, but with slight differences and improvements.

With a familar SQL syntax, it gives the ability to SELECT, INSERT, UPDATE, DELETE, COUNT documents in a collection.

Example

X-SQL
SELECT _key, title FROM articles WHERE categories='blog' LIMIT 20

Translated to CQL

CQL
{
    action: "db.fetch",
    collection: "articles",
    matches: {
        "categories": "blog"
    },
    limit: 20,
    return: "{ _key title }",
}

SDK

While it's easy to develop with Singlebase by using any HTTP/Ajax client, some libraries are available to ease you the task.

Install

npm install @singlebase/singlebase-js

Example
import createClient from '@singlebase/singlebase-js'

// Configuration
const SBCONFIG  = {
  api_url: "https://cloud.singlebaseapis.com/api",
  api_key: "YOUR.ACCESS.KEY"
}

// create the client
const sbcClient = createClient(SBCONFIG)

// a payload is a plain old JS object, which contains @action and properties
const payload = {
    action: "db.insert",            // action to take
    collection: "articles",         // collection name
    data: [                         // data to insert
        {
            title: "Hello world!",
            content: "long content...",
            views: 0
        }
    ]
}

// Request
const res = await sbClient.request(payload)

// Response
// res:{ok:bool, error:object, data:object}
if (res.ok) {
  const articleKey = res.data[0]._key
  console.log("Data", articleKey, resp.data[0])
} else {
  console.error("Unable to get data", res?.error)
}

Install

pip install singlebase

from singlebase import create_client

# Configuration
SBCONFIG = {
    "api_url": "https://cloud.singlebaseapis.com/api",
    "api_key": "YOUR.ACCESS.KEY"
}

# Create the client
sbclient = create_client(**SBCONFIG)

# A payload is a plain dict, which contains @action and properties
const payload = {
    "action": "db.insert",            // action to take
    "collection": "articles",         // collection name
    "data": [                         // data to insert
        {
            "title": "Hello world!",
            "content": "long content...",
            "views": 0
        }
    ]
}

# Request
res = sbclient.request(payload)

# Response
# res:Class{ok:bool, data:dict, error:dict}
if res.ok:
    print(res.data)
else:
    print("Error", res.error)

Concept

Overview​

Request​

API Endpoint​

Method and Content-Type​

API-KEY​

Bearer Auth Token​

Payload​

Response​

Response Status​

Rate Limit​

Pagination​

Common Query Language​

Overview​

Example​

JSON Schema​

Captcha​

Security​

Query Languages​

CQL​

X-SQL​

SDK​

Overview

Request

API Endpoint

Method and Content-Type

API-KEY

Bearer Auth Token

Payload

Response

Response Status

Rate Limit

Pagination

Common Query Language

Overview

Example

JSON Schema

Captcha

Security

Query Languages

CQL

X-SQL

SDK