FAQ and Best Practices

1. Concepts and Calling Modes

1.1 Are Instant API, WebAPI, OpenAPI, and Client API the same thing?

No.

Instant API is the set of data capabilities every dataset gets automatically — for example filter, aggregate, getOne, and create. WebAPI, OpenAPI, and Client API are the three entry points for calling those capabilities.

Concept	Role
Instant API	The standard data capabilities of a dataset
WebAPI	Cookie-session entry point, path /api/{appCode}/{datasetCode}/{method}
OpenAPI	HMAC-signed entry point, path /openapi/data/{method}
Client API	Personal-identity entry point, path /client/{appCode}/{datasetCode}/{method}

1.2 When should each mode be used?

Mode	Use cases
WebAPI	Lovrabet-generated pages, micro-frontend child apps, same-domain browser environments
OpenAPI	Third-party systems, server-side jobs, Agent gateways, cross-system integration
Client API	CLIs, Agents, local scripts, and server-side tools accessing data as an individual

The 9 raw curl APIs in this documentation use WebAPI as their primary frame of reference. For OpenAPI's signing, request bodies, and path rules, see OpenAPI.

1.3 How do the authentication methods differ?

Mode	Authentication	Header or credential
WebAPI	Cookie session authentication	Cookie
OpenAPI	HMAC-SHA256 signature	X-Time-Stamp, X-App-Code, X-Dataset-Code, X-Token
Client API	Personal identity authentication	X-User-AK

The AccessKey must stay on the server. Never put it in frontend code, public repositories, or logs.

2. API Coverage and Naming

2.1 Why "9+"?

The core documentation currently focuses on 9 commonly used capabilities: filter, aggregate, getOne, create, batchCreate, update, delete, getSelectOptions, and excelExport. The "+" in 9+ leaves room for additional standard dataset capabilities in the future.

2.2 Does OpenAPI support all 9 Instant APIs?

No.

WebAPI and Client API cover all 9 core Instant APIs. OpenAPI currently supports a subset of data operations — filter, aggregate, getOne, create, batchCreate, and update — while delete, getSelectOptions, and excelExport are not yet available through OpenAPI.

2.3 Should getList still be covered?

New documentation recommends filter. If older docs or legacy code mention getList, treat it as a compatibility concept — don't present it as the recommended entry point.

3. Calling Methods and SDKs

3.1 Where should the Node.js SDK docs live?

The Instant API documentation only maps raw APIs to SDK methods; it does not duplicate the full SDK reference. For Node.js / TypeScript SDK installation, configuration, authentication, model declarations, typing, and error handling, see TypeScript SDK.

3.2 Where should the Java SDK docs live?

For Java server-side integration, request objects, authentication, and call examples, see Java SDK. The Instant API documentation does not duplicate the full Java SDK reference.

3.3 Where should the detailed OpenAPI docs live?

For OpenAPI authentication, signing, paths, request bodies, and the full API reference, see OpenAPI.

4. Relation to SQL, Endpoints, and Hooks

4.1 Can filter replace SQL?

No. filter handles list and conditional queries; aggregate covers common statistics. For complex SQL logic, window functions, multi-level subqueries, and fixed reports, use Custom SQL.

4.2 Instant API or Backend Function Endpoint — how do I choose?

If the requirement can be expressed as a standard action on a single dataset, prefer Instant API. Use an Endpoint when you need to work across multiple datasets, call external services, or orchestrate transactions and asynchronous flows.

An Endpoint can call Instant APIs internally, but the Endpoint itself is a higher-level business orchestration entry point.

4.3 Do Hooks affect all callers?

Hooks sit on the backend execution chain of Instant API. Calls made through WebAPI, Client API, and the Instant APIs that OpenAPI supports all trigger the corresponding Before Hook / After Hook consistently.

Two caveats:

• delete, getSelectOptions, and excelExport are not yet supported on OpenAPI, so no OpenAPI call chain exists for them.
• Custom SQL and Endpoints are not standard actions on a single dataset, so don't assume they trigger that dataset's Instant API Hooks by default.

5. Best Practices

5.1 How to reduce risk on write operations

• Confirm the dataset details and fields first.
• In automation scenarios, run a dry-run or an equivalent pre-check first.
• Require explicit confirmation for deletes.
• Put business validation in Before Hooks.
• In production, prefer soft deletes and audit trails.

5.2 Why do dropdowns use getSelectOptions?

Because many forms only need the option data of a dataset — not the full list, and not a hand-written options endpoint. The principle is simple: whoever owns the data provides the options.

5.3 Documentation maintenance rules

• Use Instant API consistently in new documentation.
• Always state the count as 9+.
• Keep the raw curl APIs for the 9 core APIs and their Node.js SDK wrapper notes together in Instant API: 9 Raw APIs and the Node.js SDK.
• Point SDK details to the TypeScript SDK / Java SDK docs instead of duplicating the full SDK reference in the Instant API docs.
• Point OpenAPI details to the OpenAPI docs; don't infer OpenAPI request bodies from the WebAPI curl examples.