Overview

Singlebase provides a comprehensive suite of APIs for building modern applications with built-in data storage, authentication, and file management capabilities. All APIs use a consistent POST-based interface with standardized authentication and query patterns powered by DDO.

Singlebase API Structure

Single API Endpoint

All Singlebase services use one unified API endpoint:

[POST] https://cloud.singlebaseapis.com/api/<$PROJECT-ID>

Instead of multiple endpoints for different operations, everything goes through this single URL using different op (operation) parameters in the request body.

Getting Your Project-ID

To get your PROJECT-ID login to your console and access your project settings.

Authentication Headers

All API requests require these headers:

X-API-KEY: your_project_api_key
Authorization: Bearer your_jwt_token
Content-Type: application/json

DDO

DDO are simple dictionaries that describe data operations:

{
  "field": "value",
  "field:$operator": "condition_value",
  "nested.field": "nested_value"
}

Common DDO Query Operators

Operator	Description	Example
$eq	Equal to	{"status": "active"}
$ne	Not equal to	{"status:$ne": "deleted"}
$gt	Greater than	{"age:$gt": 18}
$gte	Greater than or equal	{"price:$gte": 100}
$lt	Less than	{"created_at:$lt": "2024-01-01"}
$lte	Less than or equal	{"score:$lte": 50}
$in	Value in array	{"category:$in": ["tech", "science"]}
$nin	Value not in array	{"status:$nin": ["deleted", "archived"]}
$exists	Field exists	{"email:$exists": true}
$regex	Regular expression	{"name:$regex": "^John"}

Examples

Simple field matching:

{
  "status": "active",
  "category": "electronics"
}

Range queries:

{
  "price:$gte": 100,
  "price:$lte": 500,
  "created_at:$gt": "2024-01-01T00:00:00Z"
}

Array operations:

{
  "tags:$in": ["featured", "bestseller"],
  "status:$nin": ["deleted", "hidden"]
}

Complex nested queries:

{
  "user.profile.verified": true,
  "user.permissions:$in": ["read", "write"],
  "metadata.category": "premium"
}

Common Request Patterns

Datastore Operations

// Find documents
{
  "op": "collection.find",
  "collection": "products",
  "match": {
    "category": "electronics",
    "price:$lte": 1000
  },
  "sort": "created_at desc",
  "limit": 50
}

// Insert document
{
  "op": "collection.insert",
  "collection": "users",
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "status": "active"
  }
}

// Update documents
{
  "op": "collection.update",
  "collection": "orders",
  "match": {
    "status": "pending",
    "created_at:$lt": "2024-01-01"
  },
  "data": {
    "status": "expired"
  }
}

Auth Operations

// Sign in
{
  "op": "auth.signin",
  "grant_type": "password",
  "email": "user@example.com",
  "password": "securePassword"
}

// Update profile
{
  "op": "auth.update_profile",
  "id_token": "current_jwt_token",
  "refresh_token": "current_refresh_token",
  "data": {
    "display_name": "New Name",
    "metadata": {"department": "Engineering"}
  }
}

Storage Operations

// Get file info
{
  "op": "file.info",
  "_key": "file_abc123",
  "signed_ttl": 3600
}

// Presign upload
{
  "op": "file.presign_upload",
  "filename": "document.pdf",
  "content_type": "application/pdf",
  "public_read": false,
  "metadata": {"category": "documents"}
}

Standard Response Format

All APIs return consistent response structures:

Success Response

{
  "data": {
    // Operation-specific data
  },
  "meta": {
    // Optional metadata (pagination, etc.)
  }
}

Error Response

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      // Additional error context
    }
  }
}

Pagination

Datastore API supports comprehensive pagination for large result sets:

Pagination Parameters

{
  "op": "collection.find",
  "collection": "products",
  "match": {"status": "active"},
  "limit": 50,
  "offset": 0,
  "sort": "created_at desc"
}

Pagination Response

{
  "data": [
    // Array of documents
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_pages": 10,
      "size": 500,
      "count": 50,
      "has_next": true,
      "next_page": 2,
      "has_prev": false,
      "prev_page": null,
      "page_showing_start": 1,
      "page_showing_end": 50
    }
  }
}

Pagination Fields

• page: Current page number
• per_page: Items per page
• total_pages: Total number of pages
• size: Total number of items
• count: Items in current page
• has_next: Whether next page exists
• next_page: Next page number (if available)
• has_prev: Whether previous page exists
• prev_page: Previous page number (if available)
• page_showing_start: First item number on current page
• page_showing_end: Last item number on current page

Pagination Example

// Fetch paginated results
async function fetchAllProducts() {
  let allProducts = [];
  let currentPage = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch('/collection.find', {
      method: 'POST',
      headers: {
        'X-API-KEY': 'your-api-key',
        'Authorization': 'Bearer your-token',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        op: 'collection.find',
        collection: 'products',
        match: { status: 'active' },
        limit: 100,
        offset: (currentPage - 1) * 100
      })
    });

    const result = await response.json();
    allProducts.push(...result.data);
    
    hasMore = result.meta.pagination.has_next;
    currentPage++;
  }

  return allProducts;
}

Best Practices

1. Authentication Management

• Store JWT tokens securely (HttpOnly cookies for web apps)
• Implement automatic token refresh before expiration
• Handle authentication failures gracefully with re-login flows

2. Query Optimization

• Use specific DDO match criteria to reduce result sets
• Implement pagination for large datasets
• Use appropriate indexes for frequently queried fields

3. Error Handling

• Implement exponential backoff for retries
• Log errors with sufficient context for debugging
• Provide user-friendly error messages

4. Performance

• Cache frequently accessed data when appropriate
• Use batch operations for multiple related requests
• Monitor API usage and optimize based on rate limits

5. Security

• Never expose API keys in client-side code
• Validate all user inputs before sending to API
• Use HTTPS for all API communications
• Implement proper access controls in your application logic

This comprehensive overview provides the foundation for working with all Singlebase APIs using consistent patterns and best practices.