OpenAPI Introduction

Welcome to Lovrabet OpenAPI! This is a secure and efficient data interface service that enables you to access business data on the Lovrabet platform programmatically.

Beta Phase

OpenAPI is currently in beta phase and only available to selected partners. To request access, please contact your business manager.

What is Lovrabet OpenAPI?

Lovrabet OpenAPI is a data interface service designed for enterprise applications, using HMAC-SHA256 signature-based authentication to ensure the security and integrity of data transmission.

Core Features

• Secure Authentication - HMAC-SHA256 signature-based authentication with multiple authentication modes
• Ready to Use - Official SDK automatically handles authentication, signing, and token management
• Multi-Environment Support - Supports both server-side (Node.js) and browser environments
• Powerful Queries - Supports pagination, sorting, filtering, and other advanced features
• TypeScript - Complete type definitions and intelligent hints
• Permission Isolation - Application-level data access control

Three Authentication Modes

Based on runtime environment and usage scenarios, OpenAPI provides three authentication methods:

1. Server-Side Mode - Using accessKey

Use Case: Node.js server-side, SSR (Server-Side Rendering), API routes

Use accessKey to generate tokens in real-time without pre-generation:

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY, // Read from environment variable
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// Direct call, SDK handles authentication automatically
const users = await client.models.users.filter();

2. Browser Token Mode - Pre-generated Token

Use Case: Browser-side public data access, non-logged-in users

Server generates token, browser uses it:

// Step 1: Server generates token (e.g., Next.js API route)
import { generateOpenApiToken } from "@lovrabet/sdk";

export async function GET() {
  const result = await generateOpenApiToken({
    appCode: "your-app-code",
    datasetCode: "ds-001",
    accessKey: process.env.LOVRABET_ACCESS_KEY,
  });

  return Response.json(result); // { token, timestamp, expiresAt }
}

// Step 2: Browser uses token
const { token, timestamp } = await fetch("/api/token").then((r) => r.json());

const client = createClient({
  appCode: "your-app-code",
  token: token,
  timestamp: timestamp,
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

3. Browser Cookie Mode - Using User Login State

Use Case: Logged-in users accessing private data

No authentication information needed, automatically uses browser cookies:

const client = createClient({
  appCode: "your-app-code",
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// Request automatically carries user login cookie
const users = await client.models.users.filter();

How to Choose Authentication Mode?

• Server-side? Use accessKey mode
• Browser + Public data? Use pre-generated token mode
• Browser + Logged-in user? Use cookie mode

Use Cases

1. Data Integration and Synchronization

Integrate Lovrabet platform business data into your enterprise systems:

• BI Reporting Systems - Periodically sync data to data warehouse for management reports
• ERP Integration - Interface with enterprise ERP systems for data interoperability
• Data Hub - Access as data source for enterprise data hub

2. Custom Application Development

Build your dedicated applications based on Lovrabet data:

• Mobile Applications - Provide data interface support for mobile platforms
• WeChat Mini Programs - Rapidly develop lightweight business applications
• Web Applications - Build customized web management systems

3. Data Analysis and Mining

Leverage OpenAPI for in-depth data analysis:

• Real-time Monitoring - Build business data real-time monitoring dashboards
• Data Analysis - Export data for statistical analysis and mining
• Trend Prediction - Business prediction based on historical data

4. Automated Workflows

Achieve business process automation through APIs:

• Scheduled Tasks - Automatically execute data queries and export tasks
• Event Triggering - Trigger business processes based on data changes
• Batch Processing - Efficiently process large batch data queries

Current Capabilities

Feature Scope

OpenAPI currently supports full CRUD operations (query, create, update) with application-level data access. Delete operations are currently only available in WebAPI (cookie authentication) mode.

Available Endpoints

OpenAPI provides the following endpoints, base URL: https://runtime.lovrabet.com

Endpoint	HTTP Path	SDK Method	Description
Batch Query	POST /openapi/data/get-list	getList(params?, sortList?)	Paginated query with filtering, sorting
Single Query	POST /openapi/data/get-one	getOne(id)	Get single record details by ID
Create Data	POST /openapi/data/create	create(data)	Create new data record
Update Data	POST /openapi/data/update	update(id, data)	Update existing record (partial update)

Complete API Reference

For detailed endpoint parameters, request/response format descriptions, please refer to the API Reference documentation.

Endpoint Usage Examples

// Batch query (supports pagination, sorting, filtering)
const users = await client.models.users.filter(
  {
    currentPage: 1,
    pageSize: 20,
    status: "active", // Filtering
  },
  [
    { priority: SortOrder.DESC }, // Multi-field sorting
    { createTime: SortOrder.DESC },
  ]
);

// Query single record
const user = await client.models.users.getOne(123);

// Create data
const newUser = await client.models.users.create({
  name: "John Doe",
  email: "john@example.com",
});

// Update data
const updated = await client.models.users.update(123, {
  status: "inactive",
});

Authentication Method

All OpenAPI requests require HMAC-SHA256 signature authentication, authentication information is passed via HTTP Headers:

Header Name	Description	Example
X-Time-Stamp	Request timestamp (ms)	1758903130713
X-App-Code	Application code	app-c2dd52a2
X-Dataset-Code	Dataset code	0fefba76fe29440194841f4825df53ff
X-Token	HMAC-SHA256 signature	jdqqGtzecF2I6FIW...

The SDK automatically handles all authentication details, no need to manually add these headers.

Coming Soon

• Delete Operations - delete() method in OpenAPI mode (currently only WebAPI mode supports)
• Webhook Notifications - Real-time push notifications for data changes
• Batch Operations - Support for batch create, update, import/export
• File Upload - Support for file field upload and management

Response Structure

All OpenAPI endpoints follow a unified response format.

getList Response Format

{
  "success": true,
  "msg": "Operation successful",
  "data": {
    "paging": {
      "pageSize": 10,
      "totalCount": 100,
      "currentPage": 1
    },
    "tableData": [
      {
        "id": "123",
        "name": "Sample Data",
        "status": "active",
        "gmt_create": "2024-01-01 12:00:00"
      }
    ],
    "tableColumns": [
      {
        "title": "ID",
        "dataIndex": "id"
      },
      {
        "title": "Name",
        "dataIndex": "name"
      }
    ]
  }
}

Fixed Field Description:

• paging - Pagination information (total count, current page, page size)
• tableData - Actual data list array
• tableColumns - Table column definition metadata, can be used to dynamically build UI

Security Best Practices

Important Security Notice

NEVER expose accessKey in browser-side code!

Incorrect:

// Dangerous! Will expose secret key
const client = createClient({
  accessKey: "sk_live_xxx", // Don't do this!
});

Correct:

// Server-side: Use environment variables
const client = createClient({
  accessKey: process.env.LOVRABET_ACCESS_KEY,
});

// Browser: Use pre-generated token
const { token } = await fetch("/api/token").then((r) => r.json());
const client = createClient({ token });

Security Mechanisms

1. Token Expiration - Each token is valid for 10 minutes, automatically expires after
2. Signature Verification - All requests must carry correct HMAC-SHA256 signature
3. HTTPS Enforcement - Production environment enforces HTTPS encrypted transmission
4. Application Isolation - Each application can only access authorized datasets
5. Environment Variables - Sensitive information stored in environment variables, not committed to code repository

Data Permissions

• Application Isolation - Each application can only access authorized datasets
• Field Permissions - Supports field-level access control
• Row-Level Permissions - Supports data row-level filtering

SDK Support

To simplify development, we provide an official SDK:

npm install @lovrabet/sdk
# or
bun add @lovrabet/sdk

SDK Advantages:

• Automatically handles authentication and signing
• Automatically manages token lifecycle
• Complete TypeScript type support
• Unified error handling

Resources:

• npm package
• GitHub repository
• Full documentation

Getting Access

1. Apply for Access

Please contact your business manager and provide the following information:

• Company name and business scenario description
• Expected API call volume and concurrency requirements
• List of datasets to access
• Technical contact information

2. Get Credentials

After approval, you will receive:

• App Code - Application unique identifier
• Access Key - Access key (please keep it safe)
• Dataset Codes - List of authorized datasets

Technical Specifications

API Specifications

• Protocol: HTTPS
• Method: POST
• Encoding: UTF-8
• Format: JSON

Environment

Environment	Domain
Production	https://runtime.lovrabet.com

Next Steps

Ready to get started with OpenAPI? We recommend following this order:

1. Quick Start - Complete your first API call in 5 minutes
2. Authentication Guide - Learn about three authentication modes and token management
3. API Reference - View complete endpoint documentation and advanced usage

Start with Quick Start

If this is your first time, we recommend checking out the Quick Start documentation to get started quickly with practical examples.

Support and Feedback

For technical support or any questions, please contact us:

• Technical Support: Contact your business manager for technical support contact information
• Developer Documentation: Continuously updated
• Online Support: Weekdays 9:00-18:00