> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ferrum.thalamiq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read Resource

> Retrieve a FHIR resource by its type and ID

Retrieves the current version of a specific resource by its logical ID.

## Endpoint

```
GET /fhir/{resourceType}/{id}
```

<ParamField path="resourceType" type="string" required>
  The FHIR resource type (e.g., `Patient`, `Observation`, `Encounter`)
</ParamField>

<ParamField path="id" type="string" required>
  The logical ID of the resource
</ParamField>

## Headers

<ParamField header="Accept" type="string">
  Response format: `application/fhir+json` (default) or `application/fhir+xml`
</ParamField>

<ParamField header="If-None-Match" type="string">
  Conditional read. Only return resource if version differs from provided ETag.

  Example: `W/"5"` - Returns `304 Not Modified` if current version is still "5"
</ParamField>

<ParamField header="If-Modified-Since" type="string">
  Conditional read. Only return resource if modified after this timestamp.

  Example: `Mon, 12 Jan 2026 10:00:00 GMT`
</ParamField>

## Response

### 200 OK

Resource found and returned.

<ResponseField name="id" type="string" required>
  The logical ID of the resource
</ResponseField>

<ResponseField name="meta.versionId" type="string" required>
  Current version number
</ResponseField>

<ResponseField name="meta.lastUpdated" type="string" required>
  ISO 8601 timestamp of last modification
</ResponseField>

<ResponseExample>
  ```json Patient Response theme={null}
  {
    "resourceType": "Patient",
    "id": "123",
    "meta": {
      "versionId": "5",
      "lastUpdated": "2026-01-12T10:30:00.000Z"
    },
    "name": [
      {
        "use": "official",
        "family": "Doe",
        "given": ["John", "Michael"]
      }
    ],
    "gender": "male",
    "birthDate": "1990-01-01",
    "identifier": [
      {
        "system": "http://hospital.example/mrn",
        "value": "12345"
      }
    ],
    "telecom": [
      {
        "system": "phone",
        "value": "555-0100",
        "use": "home"
      }
    ]
  }
  ```

  **Headers:**

  ```
  HTTP/1.1 200 OK
  Content-Type: application/fhir+json
  ETag: W/"5"
  Last-Modified: Mon, 12 Jan 2026 10:30:00 GMT
  ```
</ResponseExample>

### 304 Not Modified

Conditional read succeeded, resource hasn't changed (when using `If-None-Match` or `If-Modified-Since`).

<ResponseExample>
  **No body returned**

  **Headers:**

  ```
  HTTP/1.1 304 Not Modified
  ETag: W/"5"
  Last-Modified: Mon, 12 Jan 2026 10:30:00 GMT
  ```
</ResponseExample>

### 404 Not Found

Resource does not exist.

<ResponseExample>
  ```json Not Found Error theme={null}
  {
    "resourceType": "OperationOutcome",
    "issue": [
      {
        "severity": "error",
        "code": "not-found",
        "diagnostics": "Resource Patient/123 not found"
      }
    ]
  }
  ```
</ResponseExample>

### 410 Gone

Resource was deleted (soft delete).

<ResponseExample>
  ```json Deleted Resource theme={null}
  {
    "resourceType": "OperationOutcome",
    "issue": [
      {
        "severity": "error",
        "code": "deleted",
        "diagnostics": "Resource Patient/123 was deleted"
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  **Accessing Deleted Resources**: Use the history endpoint to read deleted resources: `GET /fhir/Patient/123/_history/5`
</Note>

## HEAD Request

Check if a resource exists without retrieving its content.

```
HEAD /fhir/{resourceType}/{id}
```

<ResponseExample>
  **Exists:**

  ```
  HTTP/1.1 200 OK
  ETag: W/"5"
  Last-Modified: Mon, 12 Jan 2026 10:30:00 GMT
  ```

  **Not Found:**

  ```
  HTTP/1.1 404 Not Found
  ```

  **Deleted:**

  ```
  HTTP/1.1 410 Gone
  ```

  **No body returned in any case**
</ResponseExample>

## Examples

<CodeGroup>
  ```bash cURL - Basic Read theme={null}
  curl -H "Accept: application/fhir+json" \
    "https://your-server.com/fhir/Patient/123"
  ```

  ```bash cURL - Conditional Read (ETag) theme={null}
  curl -H "Accept: application/fhir+json" \
    -H 'If-None-Match: W/"5"' \
    "https://your-server.com/fhir/Patient/123"
  # Returns 304 if version is still "5", 200 with body if changed
  ```

  ```bash cURL - Conditional Read (Timestamp) theme={null}
  curl -H "Accept: application/fhir+json" \
    -H "If-Modified-Since: Mon, 12 Jan 2026 10:00:00 GMT" \
    "https://your-server.com/fhir/Patient/123"
  # Returns 304 if not modified since timestamp
  ```

  ```bash cURL - HEAD Request theme={null}
  curl -I "https://your-server.com/fhir/Patient/123"
  # Returns only headers (200/404/410), no body
  ```

  ```python Python Example theme={null}
  import requests

  url = "https://your-server.com/fhir/Patient/123"
  headers = {"Accept": "application/fhir+json"}

  response = requests.get(url, headers=headers)
  if response.status_code == 200:
      patient = response.json()
      version = patient['meta']['versionId']
      print(f"Patient version {version}")
  elif response.status_code == 404:
      print("Patient not found")
  elif response.status_code == 410:
      print("Patient was deleted")
  ```

  ```python Python - With Caching theme={null}
  import requests

  url = "https://your-server.com/fhir/Patient/123"

  # First read
  response = requests.get(url, headers={"Accept": "application/fhir+json"})
  etag = response.headers['ETag']
  patient = response.json()

  # Later read with caching
  response = requests.get(
      url,
      headers={
          "Accept": "application/fhir+json",
          "If-None-Match": etag
      }
  )
  if response.status_code == 304:
      print("Patient unchanged, using cached version")
  else:
      patient = response.json()
      etag = response.headers['ETag']
      print("Patient updated, refreshed cache")
  ```

  ```javascript JavaScript Example theme={null}
  const response = await fetch('https://your-server.com/fhir/Patient/123', {
    headers: {
      'Accept': 'application/fhir+json'
    }
  });

  if (response.status === 200) {
    const patient = await response.json();
    console.log(`Patient ${patient.id} (v${patient.meta.versionId})`);
  } else if (response.status === 404) {
    console.log('Patient not found');
  } else if (response.status === 410) {
    console.log('Patient was deleted');
  }
  ```

  ```javascript JavaScript - HEAD Request theme={null}
  const response = await fetch('https://your-server.com/fhir/Patient/123', {
    method: 'HEAD'
  });

  const exists = response.status === 200;
  const deleted = response.status === 410;
  const etag = response.headers.get('ETag');

  console.log(`Exists: ${exists}, Deleted: ${deleted}, ETag: ${etag}`);
  ```
</CodeGroup>

## Notes

<Note>
  **Case Sensitivity**: Resource IDs are case-sensitive. `Patient/abc` and `Patient/ABC` are different resources.
</Note>

<Tip>
  **Performance**: Use `If-None-Match` to avoid transferring unchanged resources. Cache the ETag from previous reads and send it with subsequent requests.
</Tip>

<Warning>
  **Versioning**: This endpoint always returns the **current** version. To read a specific historical version, use the [versioned read](/api-reference/history/versioned-read) endpoint: `GET /fhir/Patient/123/_history/5`
</Warning>

## See Also

<CardGroup cols={2}>
  <Card title="Versioned Read" href="/api-reference/history/versioned-read">
    Read a specific historical version
  </Card>

  <Card title="Search" href="/api-reference/search/type">
    Find resources by criteria
  </Card>

  <Card title="Update" href="/api-reference/endpoint/update">
    Modify a resource
  </Card>

  <Card title="Resource History" href="/api-reference/history/resource">
    View all versions of a resource
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /{resourceType}/{id}
openapi: 3.1.0
info:
  title: Ferrum API
  description: >-
    FHIR R4 RESTful API implementation. All endpoints are prefixed with `/fhir`
    and follow the FHIR specification.
  version: 1.0.0
  contact:
    name: Ferrum
    url: https://github.com/thalamiq/ferrum
  license:
    name: MIT
servers:
  - url: http://localhost:8080/fhir
    description: Local development server (default port 8080)
  - url: https://your-server.com/fhir
    description: Production server (replace with your actual server URL)
  - url: https://api.example.com/fhir
    description: Example production server
security:
  - bearerAuth: []
paths:
  /{resourceType}/{id}:
    get:
      tags:
        - CRUD
      summary: Read Resource
      description: Read a specific resource by type and ID.
      operationId: readResource
      parameters:
        - $ref: '#/components/parameters/ResourceType'
        - $ref: '#/components/parameters/Id'
        - $ref: '#/components/parameters/IfNoneMatch'
        - $ref: '#/components/parameters/IfModifiedSince'
      responses:
        '200':
          description: Resource found
          headers:
            ETag:
              description: Version identifier
              schema:
                type: string
            Last-Modified:
              description: Last modification date
              schema:
                type: string
                format: date-time
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Resource'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/Resource'
        '304':
          description: Resource not modified
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    ResourceType:
      name: resourceType
      in: path
      required: true
      description: The FHIR resource type (e.g., Patient, Observation, Encounter)
      schema:
        type: string
    Id:
      name: id
      in: path
      required: true
      description: The logical ID of the resource
      schema:
        type: string
    IfNoneMatch:
      name: If-None-Match
      in: header
      description: For conditional reads (304 Not Modified)
      schema:
        type: string
    IfModifiedSince:
      name: If-Modified-Since
      in: header
      description: For conditional reads (304 Not Modified)
      schema:
        type: string
        format: date-time
  schemas:
    Resource:
      type: object
      description: A FHIR resource. All resources have resourceType, id, and meta fields.
      required:
        - resourceType
      properties:
        resourceType:
          type: string
          description: The type of resource
        id:
          type: string
          description: Logical id of this artifact
        meta:
          $ref: '#/components/schemas/Meta'
      additionalProperties: true
    Meta:
      type: object
      description: Metadata about a resource
      properties:
        versionId:
          type: string
          description: Version specific identifier
        lastUpdated:
          type: string
          format: date-time
          description: When the resource version last changed
        profile:
          type: array
          items:
            type: string
            format: uri
          description: Profiles this resource claims to conform to
        tag:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
          description: Tags applied to this resource
        security:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
          description: Security labels applied to this resource
    OperationOutcome:
      type: object
      description: >-
        A collection of error, warning or information messages that result from
        a system action
      required:
        - resourceType
      properties:
        resourceType:
          type: string
          enum:
            - OperationOutcome
          description: Resource type
        issue:
          type: array
          items:
            $ref: '#/components/schemas/OperationOutcomeIssue'
          description: A list of issues associated with the operation
    Coding:
      type: object
      description: A reference to a code defined by a terminology system
      properties:
        system:
          type: string
          format: uri
          description: Identity of the terminology system
        version:
          type: string
          description: Version of the system - if relevant
        code:
          type: string
          description: Symbol in syntax defined by the system
        display:
          type: string
          description: Representation defined by the system
    OperationOutcomeIssue:
      type: object
      description: An issue associated with the operation
      required:
        - severity
        - code
      properties:
        severity:
          type: string
          enum:
            - fatal
            - error
            - warning
            - information
          description: Severity of the issue
        code:
          type: string
          enum:
            - invalid
            - structure
            - required
            - value
            - invariant
            - security
            - login
            - unknown
            - expired
            - forbidden
            - suppressed
            - processing
            - not-supported
            - duplicate
            - multiple-matches
            - not-found
            - deleted
            - too-long
            - code-invalid
            - extension
            - too-costly
            - business-rule
            - conflict
            - transient
            - lock-error
            - no-store
            - exception
            - timeout
            - incomplete
            - throttled
            - informational
          description: Error or warning code
        details:
          $ref: '#/components/schemas/CodeableConcept'
        diagnostics:
          type: string
          description: Additional diagnostic information about the issue
        location:
          type: array
          items:
            type: string
          description: XPath or JSONPath expression describing the location of the issue
    CodeableConcept:
      type: object
      description: >-
        A concept that may be defined by a formal reference to a terminology or
        ontology
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
        text:
          type: string
          description: Plain text representation of the concept
  responses:
    NotFound:
      description: Resource not found
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication

````