0
# Client Operations
1
2
Core client functionality for connecting to FHIR servers, creating resources and search sets, and performing direct CRUD operations. The package provides both async and sync clients with identical APIs except for async/await patterns.
3
4
## Capabilities
5
6
### Client Initialization
7
8
Create FHIR client instances with server connection parameters and configuration options.
9
10
```python { .api }
11
class AsyncFHIRClient:
12
def __init__(
13
self,
14
url: str,
15
authorization: str = None,
16
extra_headers: dict = None,
17
aiohttp_config: dict = None,
18
*,
19
dump_resource: Callable[[Any], dict] = lambda x: dict(x)
20
):
21
"""
22
Initialize async FHIR client.
23
24
Parameters:
25
- url: FHIR server base URL
26
- authorization: Authorization header value (e.g., 'Bearer TOKEN')
27
- extra_headers: Additional HTTP headers
28
- aiohttp_config: Configuration passed to aiohttp session
29
- dump_resource: Function to serialize resources for requests
30
"""
31
32
class SyncFHIRClient:
33
def __init__(
34
self,
35
url: str,
36
authorization: str = None,
37
extra_headers: dict = None,
38
requests_config: dict = None,
39
*,
40
dump_resource: Callable[[Any], dict] = lambda x: dict(x)
41
):
42
"""
43
Initialize sync FHIR client.
44
45
Parameters:
46
- url: FHIR server base URL
47
- authorization: Authorization header value (e.g., 'Bearer TOKEN')
48
- extra_headers: Additional HTTP headers
49
- requests_config: Configuration passed to requests session
50
- dump_resource: Function to serialize resources for requests
51
"""
52
```
53
54
### Resource Factory Methods
55
56
Create resource instances and search sets for FHIR operations.
57
58
```python { .api }
59
def resource(self, resource_type: str, **kwargs) -> FHIRResource:
60
"""
61
Create a new resource instance.
62
63
Parameters:
64
- resource_type: FHIR resource type (e.g., 'Patient', 'Observation')
65
- **kwargs: Resource attributes
66
67
Returns:
68
Resource instance ready for CRUD operations
69
"""
70
71
def resources(self, resource_type: str) -> FHIRSearchSet:
72
"""
73
Create a search set for resource type.
74
75
Parameters:
76
- resource_type: FHIR resource type to search
77
78
Returns:
79
SearchSet instance for building queries
80
"""
81
82
def reference(
83
self,
84
resource_type: str = None,
85
id: str = None,
86
reference: str = None,
87
**kwargs
88
) -> FHIRReference:
89
"""
90
Create a reference to a resource.
91
92
Parameters:
93
- resource_type: Resource type for reference
94
- id: Resource ID for reference
95
- reference: Full reference string (alternative to resource_type/id)
96
- **kwargs: Additional reference attributes
97
98
Returns:
99
Reference instance
100
"""
101
```
102
103
### Direct CRUD Operations
104
105
Perform Create, Read, Update, Delete operations directly on the client.
106
107
```python { .api }
108
async def get(self, resource_type: str, id: str) -> FHIRResource:
109
"""
110
Get resource by type and ID.
111
112
Parameters:
113
- resource_type: FHIR resource type
114
- id: Resource identifier
115
116
Returns:
117
Resource instance
118
119
Raises:
120
- ResourceNotFound: If resource doesn't exist
121
"""
122
123
async def create(self, resource, **kwargs):
124
"""
125
Create resource on server.
126
127
Parameters:
128
- resource: Resource instance or dict
129
- **kwargs: Additional creation parameters
130
131
Returns:
132
Created resource data
133
"""
134
135
async def update(self, resource, **kwargs):
136
"""
137
Update existing resource on server.
138
139
Parameters:
140
- resource: Resource instance with updates
141
- **kwargs: Additional update parameters
142
143
Returns:
144
Updated resource data
145
"""
146
147
async def patch(self, resource, **kwargs):
148
"""
149
Patch existing resource on server.
150
151
Parameters:
152
- resource: Resource instance with changes
153
- **kwargs: Additional patch parameters
154
155
Returns:
156
Patched resource data
157
"""
158
159
async def delete(self, resource, **kwargs):
160
"""
161
Delete resource from server.
162
163
Parameters:
164
- resource: Resource instance to delete
165
- **kwargs: Additional delete parameters
166
"""
167
168
async def save(self, resource, **kwargs):
169
"""
170
Save resource (create if new, update if exists).
171
172
Parameters:
173
- resource: Resource instance to save
174
- **kwargs: Additional save parameters
175
176
Returns:
177
Saved resource data
178
"""
179
```
180
181
### Custom Operations
182
183
Execute custom FHIR operations and interact with server endpoints directly.
184
185
```python { .api }
186
async def execute(
187
self,
188
path: str,
189
method: str = "post",
190
data: dict = None,
191
params: dict = None
192
) -> Any:
193
"""
194
Execute custom operation on FHIR server.
195
196
Parameters:
197
- path: Server endpoint path
198
- method: HTTP method (get, post, put, delete, patch)
199
- data: Request body data
200
- params: Query parameters
201
202
Returns:
203
Server response data
204
"""
205
```
206
207
## Usage Examples
208
209
### Basic Client Setup
210
211
```python
212
import asyncio
213
from fhirpy import AsyncFHIRClient, SyncFHIRClient
214
215
# Async client
216
async def async_example():
217
client = AsyncFHIRClient(
218
'https://hapi.fhir.org/baseR4',
219
authorization='Bearer your-token-here',
220
extra_headers={'Custom-Header': 'value'}
221
)
222
223
# Use client for operations
224
patient = await client.get('Patient', 'example-id')
225
print(patient['name'])
226
227
# Sync client
228
def sync_example():
229
client = SyncFHIRClient(
230
'https://hapi.fhir.org/baseR4',
231
authorization='Bearer your-token-here'
232
)
233
234
# Use client for operations
235
patient = client.get('Patient', 'example-id')
236
print(patient['name'])
237
```
238
239
### Resource Creation and Management
240
241
```python
242
async def resource_management():
243
client = AsyncFHIRClient('https://hapi.fhir.org/baseR4')
244
245
# Create new patient
246
patient = client.resource('Patient',
247
name=[{'family': 'Doe', 'given': ['John']}],
248
gender='male',
249
active=True
250
)
251
252
# Save to server
253
created_patient = await client.create(patient)
254
print(f"Created patient with ID: {created_patient['id']}")
255
256
# Update patient
257
created_patient['active'] = False
258
updated_patient = await client.update(created_patient)
259
260
# Delete patient
261
await client.delete(updated_patient)
262
```
263
264
### Custom Operations
265
266
```python
267
async def custom_operations():
268
client = AsyncFHIRClient('https://hapi.fhir.org/baseR4')
269
270
# Execute $validate operation
271
validation_result = await client.execute(
272
'Patient/$validate',
273
method='post',
274
data={
275
'resourceType': 'Patient',
276
'name': [{'family': 'Test'}]
277
}
278
)
279
280
# Get server capabilities
281
capabilities = await client.execute(
282
'metadata',
283
method='get'
284
)
285
286
# Custom search with parameters
287
search_results = await client.execute(
288
'Patient',
289
method='get',
290
params={'name': 'John', '_count': '10'}
291
)
292
```