Skip to main content
Version: v4

REST Overview

Added in: v4.2.0

Harper provides a powerful, efficient, and standard-compliant HTTP REST interface for interacting with tables and other resources. The REST interface is the recommended interface for data access, querying, and manipulation over HTTP, providing the best performance and HTTP interoperability with different clients.

How the REST Interface Works​

Harper's REST interface exposes database tables and custom resources as RESTful endpoints. Tables are not exported by default; they must be explicitly exported in a schema definition. The name of the exported resource defines the base of the endpoint path, served on the application HTTP server port (default 9926).

For more on defining schemas and exporting resources, see [TODO:reference_versioned_docs/version-v4/database/schema.md 'Schema definition'].

Configuration​

Enable the REST interface by adding the rest plugin to your application's config.yaml:

rest: true

Options:

rest:
  lastModified: true # enables Last-Modified response header support
  webSocket: false # disables automatic WebSocket support (enabled by default)

URL Structure​

The REST interface follows a consistent URL structure:

PathDescription
/my-resourceRoot path — returns a description of the resource (e.g., table metadata)
/my-resource/Trailing slash indicates a collection — represents all records; append query parameters to search
/my-resource/record-idA specific record identified by its primary key
/my-resource/record-id/Trailing slash — the collection of records with the given id prefix
/my-resource/record-id/with/multiple/partsRecord id with multiple path segments

Changed in: v4.5.0 — Resources can be defined with nested paths and accessed by exact path without a trailing slash. The id.property dot syntax for accessing properties via URL is only applied to properties declared in a schema.

HTTP Methods​

REST operations map to HTTP methods following uniform interface principles:

GET​

Retrieve a record or perform a search. Handled by the resource's get() method.

GET /MyTable/123

Returns the record with primary key 123.

GET /MyTable/?name=Harper

Returns records matching name=Harper. See Querying for the full query syntax.

GET /MyTable/123.propertyName

Returns a single property of a record. Only works for properties declared in the schema.

Conditional Requests and Caching​

GET responses include an ETag header encoding the record's version/last-modification time. Clients with a cached copy can include If-None-Match on subsequent requests. If the record hasn't changed, Harper returns 304 Not Modified with no body — avoiding serialization and network transfer overhead.

PUT​

Create or replace a record with a specified primary key (upsert semantics). Handled by the resource's put(record) method. The stored record will exactly match the submitted body — any properties not included in the body are removed from the previous record.

PUT /MyTable/123
Content-Type: application/json

{ "name": "some data" }

Creates or replaces the record with primary key 123.

POST​

Create a new record without specifying a primary key, or trigger a custom action. Handled by the resource's post(data) method. The auto-assigned primary key is returned in the Location response header.

POST /MyTable/
Content-Type: application/json

{ "name": "some data" }

PATCH​

Partially update a record, merging only the provided properties (CRDT-style update). Unspecified properties are preserved.

Added in: v4.3.0

PATCH /MyTable/123
Content-Type: application/json

{ "status": "active" }

DELETE​

Delete a specific record or all records matching a query.

DELETE /MyTable/123

Deletes the record with primary key 123.

DELETE /MyTable/?status=archived

Deletes all records matching status=archived.

Content Types​

Harper supports multiple content types for both request bodies and responses. Use the Content-Type header for request bodies and the Accept header to request a specific response format.

See Content Types for the full list of supported formats and encoding recommendations.

OpenAPI​

Added in: v4.3.0

Harper automatically generates an OpenAPI specification for all resources exported via a schema. This endpoint is available at:

GET /openapi

See Also​