# API Usage - Amakomaya Nepal FHIR Implementation Guide v2.0.0

* [**Table of Contents**](toc.md)
* **API Usage**

## 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:

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:
* Business identifiers:
* 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**
1. **Extract ****`Person.id`**** from the Bundle**
1. **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
1. If not found, create the Person using conditional create
1. Store the returned`Person.id`locally
1. Create Observations using`Person/{id}`as the subject
1. 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.

