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

# Versioned Read (vread)

> Read a specific version of a resource

## Versioned Read (vread)

Retrieve a specific version of a resource by its version ID.

<ParamField path="resource_type" 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>

<ParamField path="vid" type="string" required>
  The version ID of the resource
</ParamField>

## Endpoint

```
GET /fhir/:resource_type/:id/_history/:vid
```

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://your-server.com/fhir/Patient/123/_history/2"
  ```

  ```bash HTTP theme={null}
  GET /fhir/Patient/123/_history/2 HTTP/1.1
  Host: your-server.com
  Accept: application/fhir+json
  ```
</CodeGroup>

## Response

### Success (200 OK)

Returns the resource at the specified version:

```json theme={null}
{
  "resourceType": "Patient",
  "id": "123",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2024-01-01T13:00:00Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane"]
    }
  ],
  "gender": "male",
  "birthDate": "1990-01-01"
}
```

### Not Found (404)

Returns an error if the resource or version doesn't exist:

```json theme={null}
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Resource Patient/123/_history/2 not found"
      }
    }
  ]
}
```

## HEAD Request

Use `HEAD` to check if a specific version exists without retrieving its body:

```
HEAD /fhir/Patient/123/_history/2
```

Returns `200 OK` if the version exists, `404 Not Found` otherwise. No response body is returned.

## Use Cases

Versioned read is useful for:

* **Audit Trail**: Viewing what a resource looked like at a specific point in time
* **Rollback**: Comparing versions before reverting changes
* **Compliance**: Retrieving historical versions for regulatory requirements
* **Debugging**: Understanding how a resource changed over time

## Getting Version IDs

You can get version IDs from:

1. **Resource metadata**: The `meta.versionId` field in any resource
2. **History endpoint**: The `_history` endpoint lists all versions
3. **ETag header**: The `ETag` header in responses (format: `W/"versionId"`)

## Example Workflow

1. Read current version:
   ```bash theme={null}
   GET /fhir/Patient/123
   # Returns version 3
   ```

2. Read previous version:
   ```bash theme={null}
   GET /fhir/Patient/123/_history/2
   # Returns version 2
   ```

3. Compare versions to see what changed

## Notes

* Version IDs are sequential integers starting from 1
* Version 1 is always the original creation
* Deleted resources can still be read by version ID
* Version IDs are immutable - they never change
* Use vread to access historical versions for audit or compliance purposes


## OpenAPI

````yaml GET /{resourceType}/{id}/_history/{vid}
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}/_history/{vid}:
    get:
      tags:
        - History
      summary: Versioned Read (vread)
      description: Read a specific version of a resource.
      operationId: vreadResource
      parameters:
        - $ref: '#/components/parameters/ResourceType'
        - $ref: '#/components/parameters/Id'
        - name: vid
          in: path
          required: true
          description: The version ID
          schema:
            type: string
      responses:
        '200':
          description: Resource version
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Resource'
        '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
  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

````