REST and FHIR
Legemiddelgrunndata offers two APIs over the same source data: the REST API (/api/v1,
/api/v2) and a read-only FHIR R4 API (/fhir/r4). This page explains how they differ and how
their data maps to each other.
Recommendation: use the REST API. It is the primary API and where future development happens. The FHIR endpoints exist to ease migration for consumers that already have a FHIR-based integration. They are maintained, but no major development is planned for them.
Summary
| REST | FHIR R4 | |
|---|---|---|
| Standard | Legemiddelgrunndata JSON format | HL7 FHIR R4 (application/fhir+json) |
| Shape | One object per group, with treatment alternatives, indications and products embedded | The same data split into several linked resources |
| Paging | None; a list request returns every matching group | Search results are paged (_count defaults to 10, maximum 1,000) |
| Change tracking | since-version diff with deleted items, and Last updated |
_lastUpdated search only; no history or deleted resources |
| Authentication | API key (v1) or HelseID with DPoP (v2) | HelseID with DPoP |
| Status | Recommended; actively developed | Maintained for migration; no major development planned |
Resource mapping
Both APIs are built from the same treatment groups, reimbursement groups and FEST data. REST returns each group as one complete object. FHIR spreads the same group over several resources that reference each other, so a client has to fetch or include the related resources to get the full picture.
Treatment groups
GET /api/v{1,2}/treatment-group corresponds to four FHIR resources:
| REST | FHIR resource | Notes |
|---|---|---|
treatmentGroup |
PlanDefinition |
One per treatment group. id is the group business key. |
treatmentGroup.treatmentAlternatives[] |
PlanDefinition.action[] and ActivityDefinition |
Each action has the rank and description. When the treatment id is a valid FHIR id, the action also has a definitionCanonical to ActivityDefinition/{treatmentId}. |
treatmentAlternatives[].products[] (brand) |
MedicinalProduct |
Referenced from ActivityDefinition extensions. |
treatmentAlternatives[].products[] (package) |
MedicinalProductPackaged |
Referenced from ActivityDefinition extensions. |
| REST field | FHIR element |
|---|---|
name, description |
PlanDefinition.name, description |
diseaseGroup |
PlanDefinition extension shiDiseaseGroup |
jurisdictions |
PlanDefinition.useContext (code jurisdiction) |
validityPeriod |
PlanDefinition.effectivePeriod |
reviewDate |
PlanDefinition.lastReviewDate |
indications |
PlanDefinition.goal.addresses |
treatmentAlternatives[].rank |
PlanDefinition.action[] extension shiGuidelineRank |
treatmentAlternatives[].name, description |
ActivityDefinition.name, description |
Reimbursement groups
GET /api/v{1,2}/reimbursement-group corresponds to three FHIR resources:
| REST | FHIR resource | Notes |
|---|---|---|
reimbursementGroup |
MedicinalProductAuthorization |
One per reimbursement group. id is the group business key, leading zeros kept. |
reimbursementGroup.products[] (package) |
MedicinalProductPackaged |
Referenced from MedicinalProductAuthorization.subject. |
reimbursementGroup.products[] (brand) |
MedicinalProduct |
Referenced from MedicinalProductAuthorization.subject when the group has no active package and exactly one active brand. |
| REST field | FHIR element |
|---|---|
legalBasis |
MedicinalProductAuthorization extension reimbursementRegulation |
indications |
MedicinalProductAuthorization extension ReimbursementCode |
products |
MedicinalProductAuthorization.subject (a single reference, see Content differences) |
Products
In REST, product data is embedded in each group as products[].identifiers. For a product used
by a group, it carries the same data as the FHIR product resources:
| FHIR element | REST identifier |
|---|---|
MedicinalProduct.identifier (FEST brand id) |
FEST/LegemiddelMerkevare/Id |
MedicinalProduct.name[0].productName |
display of FEST/LegemiddelMerkevare/Id |
MedicinalProductPackaged.identifier (FEST package id) |
FEST/LegemiddelPakning/Id |
MedicinalProductPackaged.identifier (article number) |
FEST/LegemiddelPakning/Varenummer |
MedicinalProductPackaged.subject (package to brand) |
Package and brand ids in the same products[] entry |
FHIR ids are lowercase Guids; REST values are uppercase Guids. See
Shared types.
MedicinalProductPackaged references its brand through subject. Use _include and
_revinclude to get related resources in the same search; see
FHIR R4 endpoints.
Content differences
The two APIs use the same source data, but they do not return exactly the same content.
Only in REST
- Active substance ids (
FEST/LegemiddelVirkestoff/Id) for each product. - Every product in a reimbursement group. FHIR
MedicinalProductAuthorization.subjectholds at most one reference:- the package, when the group has exactly one active package;
- the brand, when the group has no active package and exactly one active brand;
- nothing in all other cases, for example several active packages.
- Treatment alternatives whose treatment id is not a valid FHIR id, for example a URL. FHIR emits
no
ActivityDefinitionor action reference for them. - The treatment alternative as defined in each group. FHIR has one
ActivityDefinitionper treatment id; when several groups use the same treatment id, the alternative from the group with the lowest business key is used. - Version metadata (
currentVersion,version,lastChanged,isDeleted) and diff requests withsince-version. See Versioning and Diff.
Only in FHIR
For products used by groups, REST has the same brand and package data as FHIR (see Products). FHIR adds only:
- Package contents (
packageItem: package type and container count), dose ids and LMR numbers onMedicinalProductPackaged. MedicinalProductandMedicinalProductPackagedresources for active FEST brands and packages that no group uses. REST only returns products as part of a group.
Handled differently
- Products not in FEST: a group can list products that do not match an active product in
FEST.
- REST removes these products from
productsby default, and hides a group that had products but has none left. Withignore-fest-validation=true, REST returns all products and marks each withisInFest(see Response format). - FHIR returns every group, whether or not its products are in FEST. Product references
(
ActivityDefinitionextensions andMedicinalProductAuthorization.subject) only point to active FEST products; other products are left out without notice. There is noisInFestflag and no option to include them. - As a result, FHIR can return a group without product references where REST hides the group by default.
- REST removes these products from
- Filtering: REST has endpoint-specific query parameters such as
indication,vare-nrandeffective-date. FHIR uses FHIR search parameters, modifiers, chaining and_include. - Errors: REST returns the error format in Errors and limits. FHIR
returns
OperationOutcomeresources. - Rate limiting: the same limit applies to both APIs, but REST v1 counts requests per API key, while REST v2 and FHIR count them per client IP address. See Errors and limits.
When to choose which
Use the REST API when:
- You are building a new integration.
- You want complete groups with all products in one response.
- You keep a local copy and want to fetch only changes with
since-version.
Use the FHIR API when:
- You already have a FHIR-based integration and want to move to Legemiddelgrunndata with as few changes as possible.
New features are added to the REST API. The FHIR API is not expected to get the same features.
Related pages
- Treatment groups and Reimbursement groups — REST endpoints and schemas
- FHIR R4 endpoints — FHIR resources, search and limitations
- Authentication — API keys and HelseID