Developer Documentation

Documentation for API consumers integrating with the Nompd API.

Contents

• Getting Started — Quickstart guide with curl examples to get up and running
• API Reference — Complete endpoint documentation with parameters, responses, and examples
• Authentication — How to authenticate using API keys and expected error responses
• Versioning and Diff — How to use version-based differential sync to fetch only changes
• Data Models — Full schema documentation for TreatmentGroup, ReimbursementGroup, and related types
• Changelog — Release notes and version history

Changelog

All notable changes to the Nompd API will be documented in this file.

The format is based on Keep a Changelog.

[3.0.0] - 2026-04-30

Breaking Changes

• Renamed Behandlingsgruppe model to TreatmentGroup — endpoint, model, and MongoDB collection all renamed for consistency with ReimbursementGroup.
  • Endpoint: GET /api/v1/behandlingsgrupper → GET /api/v1/treatmentGroup
  • Mongo collection: Behandlingsgrupper → TreatmentGroups
  • Model shape unchanged (same fields: id, name, description, diseaseGroup, jurisdictions, validityPeriod, reviewDate, indications, treatmentAlternatives)
  • No backwards-compatible parallel endpoint — consumers must migrate.

Added

• Per-document version metadata in response wrapper — VersionedItem<T> now exposes version (the sync version when this item last changed) and lastChanged (ISO-8601 timestamp). Applies to both treatmentGroup and reimbursementGroup endpoints.

[2.0.0] - 2026-04-28

Breaking Changes

• Replaced Reimbursement model with ReimbursementGroup — the endpoint, model shape, and MongoDB collection have all been renamed and restructured.

  • Endpoint: GET /api/v1/reimbursements → GET /api/v1/reimbursementGroup
  • Mongo collection: Reimbursements → ReimbursementGroups
  • Model is reduced to three fields: id, legalBasis (CodeableConcept), indications (CodeableConcept[])
  • The previous medicinalReferences array is removed pending a redesign
  • legalBasis now correctly carries the hjemmel (e.g., H-resept §950) sourced from the upstream reimbursementRegulation extension, rather than the first coding from Basis
  • indications carries the diagnoses (e.g., ICD-10 codes) sourced from Basis.Coding, with one CodeableConcept per coding

  Consumers using the old endpoint must migrate. There is no backwards-compatible parallel endpoint.

[1.1.0] - 2026-04-28

Added

• Raw FHIR persistence — Upstream FHIR resources are now stored in MongoDB alongside the converted output, sharing the same version number per sync.

  • New versioned collections: PlanDefinitions, ActivityDefinitions, RegulatedAuthorizations
  • Each wrapped in VersionedDocument<T> with the same upsert + soft-delete semantics as the output collections
  • Enables re-conversion if mapping logic changes, debugging via raw-vs-converted comparison, and full audit traceability

• Sync history — Every sync run writes one entry to the new SyncHistory collection with:

  • Version, SyncedAt, DurationMs
  • Per-collection statistics (AddedCount, UpdatedCount, UnchangedCount, DeletedCount)
  • Business keys of every added, updated, and deleted record (AddedKeys, UpdatedKeys, DeletedKeys)

• unchanged field in SyncResult — The POST /api/internal/sync response now includes a count of records that were detected as unchanged.

Changed

• Content-hash-based change detection — VersionedDocument<T> has a new ContentHash field (SHA256 of BSON). Records only receive a new Version if their hash actually changed (or their deletion state flipped). Previously every sync bumped the version on every record, which made ?sinceVersion=N return everything after each sync. Now diff queries return only the records that genuinely changed.

  • Migration impact: The first sync after deploy bumps the version on all existing records once (because they have no hash to compare against), then subsequent syncs only touch genuinely changed records.

• Sync log line — Now includes unchanged count in the structured log message.

Internal

• PlanDefinition no longer has a [BsonId] attribute — it is now embedded inside VersionedDocument<PlanDefinition>, and the wrapper holds the Mongo document ID.
• UpsertCollection<T> in SyncService now returns SyncCollectionStats (counts plus business keys) instead of a counts-only tuple.

[1.0.0] - 2026-04-13

Added

• Behandlingsgrupper endpoint (GET /api/v1/behandlingsgrupper)

  • Returns treatment groups with ranked treatment alternatives
  • Includes jurisdictions, indications, validity periods, and medicine references

• Reimbursements endpoint (GET /api/v1/reimbursements)

  • Returns reimbursement authorizations with regulation basis and indication codes
  • Includes medicine references (FEST and NOMPD)

• Version-based diff support

  • All endpoints accept ?sinceVersion=N to return only changes since a given version
  • Responses include currentVersion for clients to track their sync state
  • Deleted items are included in diff responses with isDeleted: true

• API key authentication

  • All endpoints require X-API-KEY header
  • Keys are configured server-side and issued manually

• Sync endpoint (POST /api/internal/sync)

  • Triggers a full data sync from upstream FHIR APIs
  • Intended to be called by a Kubernetes CronJob
  • Returns sync statistics (added, updated, deleted, duration)