REST Server

A Kitto^x application can expose its data views as a REST/JSON web service, in parallel to the HTML^x GUI, under the versioned base path /api/v4/{ViewName}. It runs on the sameTKWebEngine and attribute router as the GUI, so the same YAML metadata, the same business rules (TKRules) and the same ACL apply — a record created over REST behaves exactly like one entered in a form.

Like the Web Server, the REST server has no dedicated process: it is served by whatever deployment mode the app runs in (standalone, service, console, ISAPI, Apache).

The base path /api/v4 is the default and can be changed in Config.yaml with Server/RestBasePath (e.g. /rest); it applies to the whole REST tree (endpoints, token, OpenAPI, Swagger UI) at runtime, no recompile needed.

Request flow

• The router and TKWebEngine are the same ones the GUI uses — the REST tree is just another set of attribute-decorated handlers (GET/POST/PUT/PATCH/DELETE), not a parallel server.
• TKXDataService (in the core, no JSON dependency) is the shared CRUD service: it resolves the view, enforces the ACL and the model-level write flags, applies field/record rules and persists. The GUI form endpoints and the REST endpoints both flow through the same domain logic.
• IKXApiSerializer is the serialization seam; the default TKXSystemJSONSerializer uses the RTL System.JSON (correct escaping, zero third-party dependencies).
• TKXApiErrorFilter turns any exception on an /api path into a JSON envelope { "error", "code", "field"? } with a real HTTP status (400/401/403/404/405/422/500).

Enabling it (opt-in)

The REST support is opt-in and adds no JSON framework to a browser-only app. Add the umbrella unit to your UseKitto.pas, exactly as you opt into Kitto.Web.Enterprise:

uses
  Kitto.Html.All,
  Kitto.Web.Enterprise,
  Kitto.Web.Rest,   // <-- registers /api/v4/... and the token endpoint
  ...

An app that does not reference Kitto.Web.Rest exposes no /api routes and links no REST code.

The three layers

Unit	Package	Role
Kitto.Web.Data.Service.pas (TKXDataService)	Core (no JSON)	Shared CRUD service: view resolution, ACL, IsReadOnly/Prevent*, rule sequence, SaveRecord. Used by both the GUI and REST.
Kitto.Web.Rest.pas (TKXApiHandlerBase, TKXApiAuthHandler, IKXApiSerializer, TKXSystemJSONSerializer, TKXApiErrorFilter)	Opt-in	The /api/v4 handlers, the JSON serializer and the JSON error filter.
Kitto.Web.Rest.OpenAPI.pas (TKXOpenAPIBuilder, /api/v4/openapi.json)	Opt-in	OpenAPI 3.0 spec generated from the metadata with System.JSON (no Neon).
Kitto.Web.Rest.Neon.pas (planned)	Opt-in²	Only if the API ever exposes typed Delphi DTO endpoints: mapping via delphi-neon. Not needed for the metadata-driven API or for OpenAPI.

Endpoints, permissions and authentication

The endpoint table, query parameters (?start=&limit=&sort=&dir=&f_<n>=), the model-level permission flags (IsReadOnly, PreventAdding/PreventEditing/PreventDeleting) and the Bearer-token flow (POST /api/v4/token → Authorization: Bearer) are documented in full on the REST API (JSON) reference page.

The API also describes itself: GET /api/v4/openapi.json returns an OpenAPI 3.0 document generated from the metadata, and GET /api/v4/docs serves an interactive Swagger UI page (vendored, works offline). See REST API — OpenAPI / Swagger UI.

The online demos expose their REST API too — try the live Swagger UI without installing anything: HelloKitto · TasKitto (see the live demos page for credentials).

Deploying under IIS / Apache

The framework serves the REST API identically on every transport, but IIS and Apache may block the write verbs (PUT/DELETE/PATCH) before the request reaches the app:

• IIS — remove the WebDAV module for the app and allow the verbs on the ISAPI handler mapping.
• Apache — allow the verbs in the <Location>/module configuration.

The Indy hosts (Standalone / Service / Console) accept all verbs out of the box — KittoX installs an Indy OnParseAuthentication passthrough so the Bearer scheme is not rejected as "Unsupported authorization scheme". No configuration needed.

Cross-origin browser clients (CORS)

A browser page on a different origin needs CORS. It is off by default; enable it per-app under Server/CORS/AllowedOrigins in Config.yaml ('*' or a comma-separated list, optional AllowCredentials). KittoX then answers the preflight OPTIONS and adds the Access-Control-* headers on /api/v4 responses. See REST API — CORS.

Extending it

TKXApiHandlerBase is virtual. To customize a single endpoint (or add a hook) for one application, subclass it and register the subclass with TKXResourceRegistry.RegisterOverride in your initialization section — the same mechanism used for the GUI view handler. See Attribute-Based Routing — overriding an endpoint.

See also

• REST API (JSON) — the full endpoint / auth / error reference
• Web Server Configuration — the shared engine and deployment modes
• Attribute-Based Routing — how the router and RegisterOverride work