API Designer: endpoints and integration flow

What is it?

There is no single "API screen". You get APIs three ways, all declared, none hand-coded:

Route	You design	The platform serves
Entity API	an entity	/api/v1/entities/<name>/records (search, get, create, update, delete)
Provider, view, service	data artifacts	named reads, counts, lookups
Integration flow	a chain of calls across your data and external systems	one composed call
Plugin API	Java or Node code in a backend service	/api/v1/plugins/<id>/**

When to use it

Prefer the entity API, then a data service. Use an integration flow when a screen needs several calls or an external API. Write plugin code only when logic cannot be declared (configuration vs code).

The flow

Entity -> Service (validation, rules) -> API -> UI
External API -> Connector -> Integration flow -> ERP data -> Workflow

Features today

• Endpoints and methods for entities: list/search, get, create, update, delete, lookup.
• Request and response: JSON; errors use one shape with a message and field details.
• Pagination, filtering and sorting on every list endpoint (pages are the default, never unbounded).
• Validation from field constraints and entity checks, enforced on every write.
• Authentication and authorization: session token, tenant header, role permissions, field permissions, record scopes, API permissions (see Security).
• Integration Flows: a Studio list of composed calls with connection references, mapping and retries (Integrations).
• Plugin API routes registered automatically at the gateway when a service starts.
• Test cases with target type api (Testing).

Planned (placeholders)

• A dedicated visual API Designer for custom REST endpoints: path, method, request body and response schema, examples. Planned.
• API versioning policy tooling. Planned.
• Rate limiting per tenant and per API key configured in Studio. Planned.
• Idempotency keys configured per endpoint. Planned.
• Generated API documentation (OpenAPI) from metadata. Planned (see Documentation generator).

Step by step (today): expose loans to a partner

1. Create the equipment_loan entity. Its API exists at once.
2. Give a role the API permission to read it.
3. Create a data service loans-overdue (search) for the partner's query.
4. Call it with a token and check pagination: ?page=0&size=20.

Security, testing, deployment

Permissions are checked per API and per record. Test with a test case or curl. APIs deploy with the plugin; nothing else to deploy.

Troubleshooting

401: no or expired session. 403: role lacks the permission. 404 "entity not found": name mismatch or plugin not installed. See Troubleshooting.

Related

Data, Integrations, Security.