Skip to content

Commit daaee6e

Browse files
author
pbcs.ghaustein
committed
add some readme files
1 parent 69f569e commit daaee6e

4 files changed

Lines changed: 175 additions & 0 deletions

File tree

‎Client/README.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# PharmaNet API Client Example
2+
3+
This project is an example implementation of a client for the PharmaNet API. The PharmaNet API provides access to pharmaceutical data and services, and this client demonstrates how to authenticate and interact with it.
4+
5+
## Overview
6+
7+
The primary focus of this example is on setting up authorization, which is often the most challenging aspect of integrating with the PharmaNet API. Once authenticated, making API calls becomes straightforward. The code includes:
8+
9+
- **Authentication Service**: Handles OAuth2/OpenID Connect flows to obtain access tokens
10+
- **JWT Handling**: Manages JSON Web Tokens for secure communication
11+
- **API Integration**: Demonstrates how to make calls to PharmaNet endpoints
12+
- **FHIR Support**: Includes message formatting for FHIR (Fast Healthcare Interoperability Resources) standard
13+
14+
## Prerequisites
15+
16+
- .NET 6.0 or later
17+
- Access to PharmaNet API credentials (client ID, client secret, etc.)
18+
- Valid certificates for JWT signing (see `keygen.sh` for key generation)
19+
20+
## Setup
21+
22+
1. **Clone the repository**:
23+
```bash
24+
git clone <repository-url>
25+
cd PharmaNetAPIs/Client
26+
```
27+
28+
2. **Configure settings**:
29+
- Update `src/appsettings.json` with your PharmaNet API credentials
30+
- Ensure certificate paths are correctly set in the configuration
31+
32+
3. **Generate keys** (if needed):
33+
```bash
34+
cd src
35+
./keygen.sh
36+
```
37+
38+
4. **Restore dependencies**:
39+
```bash
40+
dotnet restore
41+
```
42+
43+
5. **Build the project**:
44+
```bash
45+
dotnet build
46+
```
47+
48+
## Usage
49+
50+
Run the application:
51+
52+
```bash
53+
dotnet run --project src/Client.csproj
54+
```
55+
56+
The application will:
57+
1. Authenticate with the PharmaNet API using the configured credentials
58+
2. Obtain an access token
59+
3. Demonstrate making API calls to PharmaNet services
60+
61+
## Project Structure
62+
63+
- `src/Program.cs`: Main entry point
64+
- `src/Models/`: Data models for API responses and configuration
65+
- `AccessTokenResponse.cs`: Token response structure
66+
- `JwtResponse.cs`: JWT response handling
67+
- `OidcConfiguration.cs`: OpenID Connect configuration
68+
- `FHIRMessageFormat.cs`: FHIR message formatting
69+
- `src/Services/`: Core business logic
70+
- `AuthService.cs`: Authentication implementation
71+
- `PharmanetService.cs`: PharmaNet API integration
72+
- `PostService.cs`: HTTP POST operations
73+
- `src/appsettings.json`: Configuration file
74+
- `src/keygen.sh`: Script for generating cryptographic keys
75+
76+
## Configuration
77+
78+
Key settings in `appsettings.json`:
79+
80+
- `PharmaNet`: API endpoints and credentials
81+
- `JwtSigning`: Certificate configuration for JWT signing
82+
- `OpenIdConnect`: OIDC provider settings
83+
84+
## Troubleshooting
85+
86+
- **Authentication failures**: Verify credentials and certificate validity
87+
- **API errors**: Check network connectivity and API endpoint URLs
88+
- **Certificate issues**: Ensure certificates are properly installed and paths are correct
89+
90+
## Contributing
91+
92+
This is an example project. For production use, ensure proper security practices, error handling, and logging are implemented.
93+
94+
## License
95+
96+
[Specify license if applicable]

‎Services/Common/ReadMe.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
The DocumentReference.cs file you're viewing is decompiled from the Hl7.Fhir.R4 NuGet package (version 2.0.1), which is referenced in your Common.csproj file. This is a standard FHIR R4 model class generated by Visual Studio's "Metadata as Source" feature when you navigate to the type definition.
2+
3+
The original source code for this class is part of the Firely .NET SDK for FHIR, available in the FirelyTeam/firely-net-sdk GitHub repository. You can find the DocumentReference class in the src/Hl7.Fhir.Core/Model/Generated/ directory of that repo.
4+
5+
https://github.com/FirelyTeam/firely-net-sdk

‎Services/MedicationRequestService/src/Controllers/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
The MedicationRequestController is a lightweight ASP.NET Core API controller that handles medication request transactions in the PharmaNet system. It inherits from ServiceBaseController (which contains the core logic) and exposes two endpoints:
2+
3+
- MedicationRequest (POST /api/v{version:apiVersion}/MedicationRequest/): Processes standard medication request transactions
4+
- HealthCheck (POST /healthz): Performs health checks on the service
5+
6+
Both methods delegate to the base class's PharmanetRequest() method, which:
7+
8+
- Parses incoming FHIR DocumentReference requests containing HL7v2 payloads
9+
- Performs authorization checks based on HL7 message types and user scopes
10+
- Submits requests to the underlying PharmaNet service
11+
- Returns FHIR-formatted responses
12+
13+
The incoming FHIR DocumentReference request contains a full HL7v2 message as base64-encoded data in the Attachment.Data field.
14+
15+
The controller is intentionally minimal since the shared functionality (parsing, authorization, service interaction) is centralized in ServiceBaseController. This follows a common pattern in this multi-service architecture where each service controller focuses on its specific routing and policies while reusing common infrastructure.

‎Services/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Purpose of the PharmaNet API
2+
The PharmaNet APIs serve as a modern REST/FHIR gateway that:
3+
4+
- Accepts FHIR DocumentReference requests via REST endpoints
5+
- Extracts embedded HL7v2 messages from the requests
6+
- Routes them to external PharmaNet services (likely via HL7 messaging protocols)
7+
- Returns FHIR-formatted responses back to clients
8+
9+
The authentication/authorization layer ensures proper access control, but the core functionality is indeed this translation and routing between modern web APIs and legacy HL7v2 healthcare messaging systems.
10+
11+
# PractitionerService
12+
Note: other services in this solution work in a similar way to PractitionerService.
13+
14+
## Overview
15+
`PractitionerService` is an ASP.NET Core Web API service within the PharmaNetAPIs suite. It exposes a secure HTTP endpoint that accepts FHIR-based requests and forwards them to the underlying Pharmanet proxy service.
16+
17+
This service is built on a shared service base (in `Common/src/ServiceBase`) that configures authentication, routing, Swagger, and common dependencies.
18+
19+
## Key Concepts
20+
21+
### Controller discovery & routing
22+
This service uses standard ASP.NET Core MVC controller discovery:
23+
- `Common/src/AspNetConfiguration/StartupConfiguration.cs` calls `services.AddControllers()`.
24+
- `UseRest()` calls `app.UseEndpoints(routes => routes.MapControllers());`.
25+
26+
That means any class inheriting from `ControllerBase` (or `ServiceBaseController`) decorated with `[ApiController]` is automatically discovered and instantiated per request.
27+
28+
### `PractitionerController`
29+
The controller lives in `src/Controllers/PractitionerController.cs` and exposes two POST endpoints:
30+
31+
- `/api/v{version:apiVersion}/Practitioner/` (main transaction endpoint)
32+
- `/healthz` (health check endpoint)
33+
34+
The controller is resolved via dependency injection and requires:
35+
- `ILogger<ServiceBaseController>`
36+
- `IPharmanetService`
37+
- `IHl7Parser`
38+
- `IConfiguration`
39+
- `IAuthorizationService`
40+
- `IHttpContextAccessor`
41+
42+
Those dependencies are registered in `Common/src/ServiceBase/Startup.cs` and in `Common/src/AspNetConfiguration/StartupConfiguration.cs`.
43+
44+
### Security
45+
The controller actions are protected by JWT bearer authentication and the `FhirScopesPolicy.Access` authorization policy.
46+
47+
## Running
48+
The `Program.cs` entrypoint uses `ProgramConfiguration.CreateHostBuilder<Startup>(args)` to wire up the shared startup and host configuration.
49+
50+
To run locally (from the `src` folder):
51+
52+
```bash
53+
dotnet run
54+
```
55+
56+
## Useful paths
57+
- `src/Controllers/PractitionerController.cs` - API controller implementation
58+
- `Common/src/ServiceBase/Startup.cs` - shared DI registration (services + auth + swagger)
59+
- `Common/src/AspNetConfiguration/StartupConfiguration.cs` - shared middleware pipeline and controller routing

0 commit comments

Comments
 (0)