Amakomaya Nepal FHIR Implementation Guide
1.0.1 - ci-build Nepal flag

Amakomaya Nepal FHIR Implementation Guide - Local Development build (v1.0.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

API Usage

AMK FHIR API – Developer Usage Guide

This page provides a concise, developer-focused guide for working with the AMK FHIR API. It complements the formal conformance artifacts (Profiles, ValueSets, and CapabilityStatement) with practical usage patterns, conventions, and examples.

Base URL and FHIR Version

  • Base URL: https://api.amakomaya.com
  • FHIR Version: R5
  • Content Type: application/fhir+json

All examples in this guide assume JSON encoding.

Authentication

All API requests MUST be authenticated.

  • Authentication mechanism: Basic Authentication (implementation-specific)

  • Unauthorized or forbidden requests return an OperationOutcome with HTTP status:

    • 401 Unauthorized
    • 403 Forbidden

Clients SHOULD be prepared to parse and display OperationOutcome.issue details.

General API Principles

  • All interactions are performed on FHIR resources, not on individual elements.

  • Each resource has:

    • a server-assigned logical id (Resource.id)
    • zero or more business identifiers (Resource.identifier)

  • Business identifiers:

    • are used for searching, matching, and de-duplication
    • MUST NOT be used as REST endpoint paths
  • All error responses conform to the OperationOutcome resource.

Identifier Strategy

AMK uses phone number as the primary business identifier for person-level identity.

Identifier System

https://api.amakomaya.com/NamingSystem/nepal-telecom-subscriber

Identifier Search Syntax

identifier={system}|{value}

Example

identifier=https://api.amakomaya.com/NamingSystem/nepal-telecom-subscriber|9851341921

This identifier is consistently used across Person search and conditional create operations.

Person Resource Usage

The Person resource represents a real-world individual and acts as the identity anchor for clinical, programmatic, and observational data.

To prevent duplicate Person records, clients SHOULD use conditional create.

POST /Person?identifier={system}|{value}

Behavior:

  • If a matching Person already exists, the server returns the existing resource
  • If no match is found, a new Person resource is created

This pattern is the preferred way to register or resolve a Person.

Search Person by Identifier

GET /Person?identifier={system}|{value}
  • The response is a Bundle
  • Client applications MUST extract and store the Person.id for future operations

Read Person by ID

GET /Person/{id}

Retrieves a single Person resource by logical id.

Update Person

PUT /Person/{id}
  • The full resource representation MUST be supplied
  • Partial updates are not supported unless explicitly stated in the CapabilityStatement

Delete Person

DELETE /Person/{id}

Deletes the Person resource identified by the logical id.

Observation Resource Usage

The Observation resource is used to capture measurements, findings, or events associated with a Person (for example: body weight or menstruation status).

Subject Reference

All Observations MUST reference a Person:

Observation.subject.reference = "Person/{person-id}"

The referenced Person MUST exist on the server.

Create Observation

POST /Observation
  • Observation.subject is mandatory
  • The subject reference MUST point to a valid Person/{id}

Search Observations by Subject

GET /Observation?subject=Person/{person-id}

Returns all Observations linked to the specified Person.

Searching Observations Using a Person Identifier (Two-Step Pattern)

FHIR does not support server-side joins across resources.

To retrieve Observations when only a Person identifier is known, clients MUST follow this pattern:

  1. Search Person by identifier
  2. Extract **Person.id** from the Bundle
  3. Search Observations using the subject reference

This two-step workflow is REQUIRED and is the standard FHIR approach.

A typical client interaction SHOULD follow this sequence:

  1. Search for a Person using the business identifier
  2. If not found, create the Person using conditional create
  3. Store the returned Person.id locally
  4. Create Observations using Person/{id} as the subject
  5. Query Observations using the subject search parameter

This approach ensures data consistency and prevents duplicate identity records.

Date and Time Handling

  • All date and time values SHOULD include timezone offsets
  • Nepal timezone example:
2025-12-17T06:30:00+05:45

Clients SHOULD NOT assume server-side timezone normalization.

Capability Statement

Clients MUST rely on the server’s CapabilityStatement as the authoritative source for:

  • Supported resources
  • Allowed interactions
  • Search parameters
  • Conditional operations

This guide provides usage conventions but does not replace the CapabilityStatement.

Scope of This Guide

This document focuses on:

  • Person identity management
  • Identifier-based workflows
  • Observation-to-Person linkage

Additional resources, profiles, and workflows may be introduced in future versions of the AMK FHIR Implementation Guide.