Amakomaya Nepal FHIR Implementation Guide
2.0.0 - ci-build Nepal

Amakomaya Nepal FHIR Implementation Guide - Local Development build (v2.0.0) 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.

### Conditional Create (Recommended)

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.

## Recommended Client Workflow

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.