---
name: hapi-fhir-server
description: Expert guidance for implementing FHIR servers using HAPI FHIR Plain Server framework. Use this skill when creating RESTful FHIR server implementations, implementing resource providers, adding FHIR operations (read, create, update, delete, search, $operations), implementing server interceptors for logging, security, and validation, setting up authentication and authorisation, or configuring FHIR server behaviour. Trigger keywords include "HAPI", "FHIR server", "RestfulServer", "resource provider", "IResourceProvider", "FHIR interceptor", "AuthorizationInterceptor", "FhirContext", "FHIR validation", "FHIR search", "FHIR operation".
---

# HAPI FHIR Plain Server Implementation

## Quick Start

### Basic Server Setup

```java
public class MyFhirServer extends RestfulServer {
    @Override
    protected void initialize() throws ServletException {
        setFhirContext(FhirContext.forR4());
        setResourceProviders(List.of(
            new PatientResourceProvider(),
            new ObservationResourceProvider()
        ));
        registerInterceptor(new ResponseHighlighterInterceptor());
    }
}
```

### Minimal Resource Provider

```java
public class PatientResourceProvider implements IResourceProvider {
    @Override
    public Class<Patient> getResourceType() { return Patient.class; }

    @Read
    public Patient read(@IdParam IdType id) {
        return loadPatient(id.getIdPart());
    }

    @Search
    public List<Patient> search(
            @OptionalParam(name = Patient.SP_FAMILY) StringParam family) {
        return searchPatients(family);
    }
}
```

## Server Architecture

### Component Hierarchy

```
RestfulServer (Servlet)
├── FhirContext (version-specific, expensive to create - reuse)
├── Resource Providers (IResourceProvider per resource type)
├── Plain Providers (cross-resource operations)
├── Interceptors (request/response hooks)
└── Configuration (paging, address strategy, encoding)
```

### Server vs Storage Distinction

- **SERVER_xxx pointcuts**: Request/response lifecycle hooks
- **STORAGE_xxx pointcuts**: Data persistence hooks (must be triggered manually in Plain Server)

## Core Patterns

### CRUD Operations

| Operation | Annotation            | Key Parameters                                       |
| --------- | --------------------- | ---------------------------------------------------- |
| Read      | `@Read`               | `@IdParam IdType`                                    |
| VRead     | `@Read(version=true)` | `@IdParam IdType` (with version)                     |
| Create    | `@Create`             | `@ResourceParam Patient`                             |
| Update    | `@Update`             | `@IdParam`, `@ResourceParam`                         |
| Delete    | `@Delete`             | `@IdParam IdType`                                    |
| Patch     | `@Patch`              | `@IdParam`, `PatchTypeEnum`, `@ResourceParam String` |

### Conditional Operations

Add `@ConditionalUrlParam String` to support conditional create/update/delete:

```java
@Update
public MethodOutcome update(
        @ResourceParam Patient patient,
        @IdParam IdType id,
        @ConditionalUrlParam String conditional) {
    if (conditional != null) {
        // Find by search criteria in conditional URL
    }
    // Perform update
}
```

### MethodOutcome Return

```java
MethodOutcome outcome = new MethodOutcome();
outcome.setId(new IdType("Patient", "123", "1"));
outcome.setCreated(true);  // For create operations
return outcome;
```

## Search Implementation

### Parameter Types

| Type      | Class                        | Example URL                 |
| --------- | ---------------------------- | --------------------------- |
| String    | `StringParam`                | `?family=Smith`             |
| Token     | `TokenParam`                 | `?identifier=mrn\|123`      |
| Date      | `DateParam`/`DateRangeParam` | `?date=ge2020-01-01`        |
| Reference | `ReferenceParam`             | `?subject=Patient/123`      |
| Quantity  | `QuantityParam`              | `?value-quantity=gt5\|\|kg` |

### Multi-Value Logic

```java
// OR logic (comma-separated): ?family=Smith,Jones
@OptionalParam(name = "family") StringOrListParam families

// AND logic (repeated param): ?family=Smith&family=Jones
@OptionalParam(name = "family") StringAndListParam families
```

### Paging with IBundleProvider

For large results, return `IBundleProvider` instead of `List<IBaseResource>`:

```java
@Search
public IBundleProvider search(...) {
    List<String> ids = findMatchingIds();
    return new SimpleBundleProvider(ids) {
        @Override
        public List<IBaseResource> getResources(int from, int to) {
            return loadResources(ids.subList(from, Math.min(to, ids.size())));
        }
    };
}
```

Configure paging provider on server:

```java
FifoMemoryPagingProvider paging = new FifoMemoryPagingProvider(10);
paging.setDefaultPageSize(20);
paging.setMaximumPageSize(100);
setPagingProvider(paging);
```

## Extended Operations ($operations)

```java
@Operation(name = "$everything", idempotent = true)
public Bundle everything(
        @IdParam IdType patientId,
        @OperationParam(name = "start") DateType start,
        @OperationParam(name = "end") DateType end) {
    // Return bundle with patient and related resources
}
```

- **Instance-level**: Include `@IdParam`
- **Type-level**: No `@IdParam`, register on resource provider
- **Server-level**: Register on plain provider (no `IResourceProvider`)
- `idempotent = true`: Allows HTTP GET (only for primitive params)

## Interceptors

### Registration

```java
registerInterceptor(new LoggingInterceptor());
registerInterceptor(new ResponseHighlighterInterceptor());
```

### Custom Interceptor

```java
@Interceptor
public class MyInterceptor {
    @Hook(Pointcut.SERVER_INCOMING_REQUEST_PRE_HANDLED)
    public void preHandle(RequestDetails details, HttpServletRequest request) {
        // Before request processing
    }

    @Hook(Pointcut.SERVER_OUTGOING_RESPONSE)
    public void postHandle(RequestDetails details, IBaseResource resource) {
        // After response generated
    }
}
```

### Key Pointcuts

- `SERVER_INCOMING_REQUEST_PRE_PROCESSED`: Earliest hook
- `SERVER_INCOMING_REQUEST_PRE_HANDLED`: After handler selected
- `SERVER_OUTGOING_RESPONSE`: Before response sent
- `SERVER_HANDLE_EXCEPTION`: On any exception

### Essential Built-in Interceptors

| Interceptor                      | Purpose                     |
| -------------------------------- | --------------------------- |
| `LoggingInterceptor`             | Request/response logging    |
| `ResponseHighlighterInterceptor` | HTML view for browsers      |
| `RequestValidatingInterceptor`   | Validate incoming resources |
| `ResponseValidatingInterceptor`  | Validate outgoing resources |
| `CorsInterceptor`                | CORS support                |
| `ExceptionHandlingInterceptor`   | Custom error responses      |

## Security

### Authentication Pattern

```java
@Interceptor
public class AuthInterceptor {
    @Hook(Pointcut.SERVER_INCOMING_REQUEST_PRE_HANDLED)
    public void authenticate(RequestDetails details, HttpServletRequest request) {
        String auth = request.getHeader("Authorization");
        if (!validateToken(auth)) {
            throw new AuthenticationException("Invalid credentials");
        }
        details.getUserData().put("user", extractUser(auth));
    }
}
```

### Authorisation with AuthorizationInterceptor

```java
public class MyAuthInterceptor extends AuthorizationInterceptor {
    @Override
    public List<IAuthRule> buildRuleList(RequestDetails details) {
        String userId = (String) details.getUserData().get("user");
        return new RuleBuilder()
            .allow().read().allResources()
                .inCompartment("Patient", new IdType("Patient", userId))
            .andThen()
            .allow().write().allResources()
                .inCompartment("Patient", new IdType("Patient", userId))
            .andThen()
            .denyAll()
            .build();
    }
}
```

## Validation

### Setup

```java
ValidationSupportChain chain = new ValidationSupportChain(
    new DefaultProfileValidationSupport(ctx),
    new InMemoryTerminologyServerValidationSupport(ctx),
    new CommonCodeSystemsTerminologyService(ctx)
);
FhirInstanceValidator validator = new FhirInstanceValidator(chain);
RequestValidatingInterceptor interceptor = new RequestValidatingInterceptor();
interceptor.addValidatorModule(validator);
interceptor.setFailOnSeverity(ResultSeverityEnum.ERROR);
registerInterceptor(interceptor);
```

### Profile Validation

Add `NpmPackageValidationSupport` for implementation guide validation:

```java
NpmPackageValidationSupport npm = new NpmPackageValidationSupport(ctx);
npm.loadPackageFromClasspath("classpath:package/us.core.tgz");
```

## Exception Handling

| Exception                          | HTTP Status | Use Case               |
| ---------------------------------- | ----------- | ---------------------- |
| `ResourceNotFoundException`        | 404         | Resource not found     |
| `InvalidRequestException`          | 400         | Bad request parameters |
| `UnprocessableEntityException`     | 422         | Validation failure     |
| `AuthenticationException`          | 401         | Auth required          |
| `ForbiddenOperationException`      | 403         | Access denied          |
| `ResourceVersionConflictException` | 409         | Version mismatch       |
| `InternalErrorException`           | 500         | Server error           |

## Configuration

### Server Address Strategy

```java
// For reverse proxy
setServerAddressStrategy(new HardcodedServerAddressStrategy("https://api.example.com/fhir"));

// For Apache mod_proxy
setServerAddressStrategy(new ApacheProxyAddressStrategy(true));
```

### Response Defaults

```java
setDefaultResponseEncoding(EncodingEnum.JSON);
setDefaultPrettyPrint(true);
```

### Multitenancy

```java
setTenantIdentificationStrategy(new UrlBaseTenantIdentificationStrategy());
// Access via: details.getTenantId()
```

## Detailed References

- **Resource Providers**: See [references/resource-providers.md](references/resource-providers.md)
- **Search Operations**: See [references/search.md](references/search.md)
- **Interceptors**: See [references/interceptors.md](references/interceptors.md)
- **Security**: See [references/security.md](references/security.md)
- **Extended Operations**: See [references/operations.md](references/operations.md)