Docs/API Reference

ClientAPI Reference

Backend-as-a-service layer with secure, scalable API for all data operations.

ClientAPI Reference

Overview

The ClientAPI is the backend-as-a-service layer that powers your applications. It provides a secure, scalable API for all data operations with built-in security, caching, and extensibility.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         ClientAPI                                │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    CORE (Platform)                       │    │
│  │  • Authentication & Authorization                        │    │
│  │  • Universal Row-Level Security (RLS)                    │    │
│  │  • Entity Operations (CRUD)                              │    │
│  │  • Permission Service                                    │    │
│  │  • Caching Layer                                         │    │
│  │  • Database Management                                   │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│                              ▼                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   CUSTOM (Client-Authored)               │    │
│  │  • Server Functions (TypeScript/JavaScript)              │    │
│  │  • Business Logic                                        │    │
│  │  • Third-party Integrations                              │    │
│  │  • Custom Validation                                     │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Core vs Custom

Aspect	Core	Custom
Ownership	Platform	Client
Code Visibility	Obfuscated	Full access
Updates	Automatic	Client-managed
Purpose	Infrastructure	Business logic
Examples	RLS, CRUD, auth	Order processing, reports

Authentication

API Key Authentication

http

GET /api/entities/products
Authorization: Bearer YOUR_API_KEY
X-Workspace-Id: workspace-uuid

JWT Authentication (User Context)

http

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure-password"
}

Response:

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "roles": ["admin"]
  }
}

Entity Operations

Create (POST)

http

POST /api/entities/products
Content-Type: application/json

{
  "name": "Premium Widget",
  "description": "High-quality widget for professionals",
  "price": 99.99,
  "category_id": "category-uuid",
  "is_active": true
}

Read (GET)

Find by ID

http

GET /api/entities/products/product-uuid

List with Filtering

http

GET /api/entities/products?
  filter[is_active]=true&
  filter[price][gte]=50&
  filter[category_id]=category-uuid&
  sort=-created_at&
  limit=10&
  offset=0&
  expand=category

Query Parameters

Parameter	Description	Example
`filter[field]`	Exact match	`filter[status]=active`
`filter[field][op]`	Operator	`filter[price][gte]=100`
`sort`	Order results	`sort=-created_at,name`
`limit`	Max results	`limit=25`
`offset`	Skip records	`offset=50`
`expand`	Include relations	`expand=category,tags`
`fields`	Select fields	`fields=id,name,price`

Filter Operators

Operator	Description	Example
`eq`	Equal (default)	`filter[status][eq]=active`
`ne`	Not equal	`filter[status][ne]=deleted`
`gt`	Greater than	`filter[price][gt]=100`
`gte`	Greater or equal	`filter[price][gte]=100`
`lt`	Less than	`filter[quantity][lt]=10`
`lte`	Less or equal	`filter[quantity][lte]=10`
`in`	In array	`filter[status][in]=active,pending`
`nin`	Not in array	`filter[status][nin]=deleted,archived`
`like`	Pattern match	`filter[name][like]=%widget%`
`null`	Is null	`filter[deleted_at][null]=true`

Update (PUT/PATCH)

http

PATCH /api/entities/products/product-uuid
Content-Type: application/json

{
  "price": 89.99,
  "is_active": false
}

Delete (DELETE)

http

DELETE /api/entities/products/product-uuid

Bulk Operations

Bulk Create

http

POST /api/entities/products/bulk
Content-Type: application/json

{
  "records": [
    { "name": "Product 1", "price": 29.99 },
    { "name": "Product 2", "price": 39.99 },
    { "name": "Product 3", "price": 49.99 }
  ]
}

Error Handling

Error Response Format

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing authentication
`FORBIDDEN`	403	Permission denied
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid input data
`CONFLICT`	409	Resource already exists
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limiting

Tier	Requests/min	Requests/day
Free	60	10,000
Pro	600	100,000
Enterprise	6,000	Unlimited

Rate limit headers:

http

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 542
X-RateLimit-Reset: 1705312800

SDK Usage

JavaScript/TypeScript

typescript

import { AlgorithmShiftClient } from '@algorithmshift/client';

const client = new AlgorithmShiftClient({
  workspaceId: 'workspace-uuid',
  apiKey: 'your-api-key'
});

// Entity operations
const products = await client.entities.products.find({
  where: { is_active: true },
  orderBy: { created_at: 'desc' },
  limit: 10,
  expand: ['category']
});

// Create record
const newProduct = await client.entities.products.create({
  name: 'New Product',
  price: 29.99
});

// Call custom function
const result = await client.functions.call('orders/process-order', {
  orderId: 'order-uuid',
  paymentToken: 'tok_visa'
});

React Hooks

typescript

import { useEntities, useFunction } from '@algorithmshift/react';

function ProductList() {
  const { data, loading, error, refetch } = useEntities('products', {
    where: { is_active: true },
    orderBy: { name: 'asc' }
  });

  const [processOrder, { loading: processing }] = useFunction(
    'orders/process-order'
  );

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return (
    <ProductGrid products={data} />
  );
}