Health Data Service Interface (HDSI)

Controlling Response Format

The HDSI, AMI and BIS all support a variety of response formats which are controlled by the Accept header. Valid accept headers are:
Accept
Format
application/xml
XML format optimized for synchronization interfaces
application/json
JSON format optimized for synchronization interfaces
application/json+sdb-viewmodel
JSON format optimized for HTML rendering

XML

XML is the preferred method of transport for the HDSI, AMI and BIS. XML has several advantages over the JSON format messages, especially when running SanteDB in a full .NET Framework Environment. These benefits include:
  • Pre-Compiled Serialization - The .NET framework pre-compiles serialization and parsing libraries which make the reading and writing of XML much faster.
  • Use of Streams - When using XML serialization the parser and serializer classes use .NET memory streams and stream readers. This is much faster and less memory intensive than the string based processing that the JSON formats use.
  • Easy Validation / Translation - When using XML you can leverage the XSD and XSLT functions of XML to easily validate and transform messages. SanteDB provides schemas for all payload classes in XSD.
Additionally, SanteDB offers content compression on response and request payloads. When compressed the size of the payloads over the wire are negligible when compared to compressed JSON formats.

Sync JSON

JSON format payloads which are a 1:1 map of the XML payloads can be obtained using the synchronization JSON format. These payloads are small since they make the assumption that the caller already has prior knowledge of referenced data.
When using this format, the response objects are serialized (using JSON.NET) directly to the wire. There is a performance penalty however, since JSON.NET uses string manipulation to achieve parsing and serialization.

ViewModel JSON

ViewModel JSON is a convenience method of serialization, and is intended for use when the client may not have the ability (or desire) to synchronize data with the entire server. ViewModel JSON works by expanding (lazy loading) properties and including them as nested objects in the response payload.
This is extremely helpful when rendering data, consider, for example, the following patient result:
1
GET http://my.server/hdsi/Patient/0ea6e373-5763-41a6-a5f3-daa0b2c01b62 HTTP/1.1
2
Accept: application/json
3
Accept-Encoding: gzip
Copied!
The response of this message would be:
1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Content-Length: 3945
4
Content-Encoding: gzip
5
6
{
7
"$type" : "Patient",
8
...
9
"relationship": [
10
{
11
"relationshipType": "24380d53-ea22-4820-9f06-8671f774f133",
12
"target": "0f4ae60a-c6af-4cf3-a786-a52b4401df65"
13
}
14
]
15
}
Copied!
This API is useful if the caller has an idea what the relationshipType UUID means and what the target entity is (they can, of course fetch these). However, when using the view model classes:
1
GET http://my.server/hdsi/Patient/0ea6e373-5763-41a6-a5f3-daa0b2c01b62 HTTP/1.1
2
Accept: application/json+sdb-viewmodel
3
Accept-Encoding: gzip
Copied!
The response will comprise of a JSON bundle with additional contextual information.
1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Content-Length: 3945
4
Content-Encoding: gzip
5
6
{
7
"$type" : "Patient",
8
...
9
"relationship": {
10
"Brother": [
11
{
12
"$type": "EntityRelationship",
13
"relationshipType": "24380d53-ea22-4820-9f06-8671f774f133",
14
"target": "0f4ae60a-c6af-4cf3-a786-a52b4401df65",
15
"targetModel": {
16
"$type": "Person",
17
...
18
}
19
}
20
]
21
}
22
}
Copied!
While this consumes more bandwidth, it does save roundtrips to the server.

Request / Response Compression

SanteDB is designed to work in low-resource environments with high latency narrowband networks. This means that SanteDB provides a variety of data compression algorithms which can be specified when interacting with the server.
Request payloads which are compressed are indicated using the Content-Encoding HTTP header and the Accept-Encoding HTTP header to control the compression of the response.
1
PUT /hdsi/Patient/fb00e97a-bdfc-403d-8f62-52f8e6846a16 HTTP/1.1
2
Authorization: BASIC ZmlkZGxlcjpmaWRkbGVy
3
Host: demo.openiz.org:8080
4
Content-Encoding: gzip
5
Accept-Encoding: gzip
6
7
<<< GZIP COMPRESSED BINARY PAYLOAD >>>
8
9
HTTP/1.1 201 Created
10
Content-Encoding: gzip
11
X-CompressResponseStream: gzip
12
13
<<< GZIP COMPRESSED BINARY PAYLOAD >>>
Copied!
The compression algorithms supported by SanteDB are:
Algorithm
Header
Description
GZIP Compress
gzip
Uses the GZIP compression algorithm for payloads (default)
BZIP2 Compress
bzip2
Uses the BZIP2 compression algorithm
Deflate Compress
deflate
Uses the ZIP deflate compression algorithm (df)
LZMA Compress
lzma
Uses the LZMA / 7ZIP compression algorithm.
This option uses more CPU resources on compression however results in much slower payload sizes.

Related Topics