Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Using the API

EHRbase-rs exposes the openEHR REST API (ITS-REST 1.0.3): a resource-based HTTP interface for creating EHRs, committing and retrieving versioned clinical documents, managing folders and contributions, and running queries. This part is the practical reference for client developers — the resources and their operations, the headers that drive versioning and content negotiation, and the error contract. The complete, machine-generated endpoint reference (every path, parameter, and schema) is published separately as the API reference on the documentation site (under /ehrbase-rs/api/); this book explains how to use it.

Base path

All clinical API routes hang off a configurable base path, which defaults to:

/ehrbase/rest/openehr/v1

Every path in these chapters is relative to that base. So “POST /ehr” means POST http://your-host:8080/ehrbase/rest/openehr/v1/ehr. The base path is set with EHRBASE_REST_BASE_PATH (see the configuration reference).

The public, unauthenticated status probe lives just outside the base path at /ehrbase/rest/status, and interactive docs at /ehrbase/swagger-ui when enabled.

Authentication

Requests are authenticated unless auth is explicitly disabled. Two mechanisms ship in Stage 1:

  • HTTP Basic — a configured user store; send Authorization: Basic .... The examples in this book use -u user:password with curl.
  • OAuth2 / OIDC bearer tokens — send Authorization: Bearer <token>, validated against a configured issuer (Keycloak, Active Directory, any standards-compliant provider).

A request with no or invalid credentials gets 401 Unauthorized; an authenticated caller lacking the required role gets 403 Forbidden. Authorization is coarse role-based access control by default (a USER role for clinical operations, an ADMIN role for admin operations), with optional attribute-based policies. The full picture — mechanisms, roles, multi-tenancy — is in Security & multi-tenancy.

Note

The development stack ships throwaway Basic users (ehrbase / ehrbase). Replace them before any real use.

The chapters here

  • Resource walkthroughs — EHR, EHR_STATUS, COMPOSITION, DIRECTORY, and CONTRIBUTION, each with real curl examples, the headers they need, and the status codes they return.
  • Content negotiation & errors — choosing JSON or XML, the Prefer header, ETag/If-Match optimistic concurrency, and the error response shape.

For querying, see Querying with AQL; for loading templates, Templates & validation.