openEHR REST Client
ToolsThe Problem
Working with an openEHR CDR from a JVM application means calling a REST API with specific request formats, content types, and error semantics defined by the openEHR ITS REST specification. Writing these HTTP calls by hand is repetitive: you handle authentication, set the right headers, serialize the request body, send it, check the status code, and deserialize the response — for every operation, in every application that touches the CDR.
Without a shared client library, each JVM project that integrates with an openEHR CDR implements its own HTTP wrapper — inconsistently, with different error handling assumptions, and often missing edge cases in the specification. The duplication is unnecessary and the inconsistencies cause bugs.
Why We Built It
The REST Client was created during integration projects where the target application was written in Groovy or Java and needed to interact with an openEHR CDR. In early projects we wrote the HTTP layer inline — request builders, response parsers, retry logic — scattered across application code. That worked once, but the second time we needed it in a different project we extracted it into a standalone library.
The result covers all major openEHR ITS REST API operations: creating and querying EHRs, storing and retrieving compositions, uploading templates, and executing AQL queries. Because it is written in Groovy and compiles to the JVM, it works from Java, Kotlin, and any other JVM language without modification.
The client is designed to be server-agnostic. It works against any openEHR-compliant CDR — including Atomik, EHRServer, EHRBase, and others. Switching CDR implementations does not require rewriting the integration layer.
Key Capabilities
What the client handles so your application code does not have to.
Full API coverage
Covers all major openEHR ITS REST API operations: EHR management, Composition CRUD, Template upload and retrieval, Contribution, and AQL Query. No partial support — if the spec defines it, the client has a method for it.
JVM-compatible Groovy implementation
Written in Groovy, which means it compiles to standard JVM bytecode. Java projects can use it as a dependency without any Groovy knowledge or runtime changes.
Authentication and request formatting
Handles authentication headers, content-type negotiation, and request body serialization. The calling code provides data objects; the client handles the HTTP details.
Server-agnostic by design
Compatible with any openEHR ITS REST-compliant server. Tested against Atomik, EHRServer, and EHRBase. Switching CDR vendors does not require rewriting integration code.
Do you have any questions?
Let us know how we can help you.