pub struct Client { /* private fields */ }Expand description
A client for one FHIR terminology server.
The client is cheap to clone: the HTTP stack and the configuration are shared, so a clone carries the same connection pool.
Implementations§
Source§impl Client
impl Client
Sourcepub fn new(config: Config) -> Result<Self, Error>
pub fn new(config: Config) -> Result<Self, Error>
Returns a client for the server config describes.
This constructor is the only way to obtain a client, so a deployment
that configures no terminology server holds no Client at all and
the absence is a compile-time Option<Client> rather than a runtime
fallback.
§Errors
Returns Error::BaseUrl when the base URL cannot carry a path, and
Error::ClientBuild when the HTTP stack refuses the configuration.
Sourcepub fn check(&self, request: &Request) -> Result<(), Error>
pub fn check(&self, request: &Request) -> Result<(), Error>
Checks that the configured release can carry request, sending
nothing.
A caller that sends several requests uses this to set aside one the release cannot carry, since a batch holding it is refused whole.
§Errors
Returns Error::UnsupportedParameter when request names a
parameter the configured release does not declare: a concept map
url or a value set version on an STU3 client.
Sourcepub async fn reachability(&self) -> Result<StatusCode, Error>
pub async fn reachability(&self) -> Result<StatusCode, Error>
Returns the status the server answers GET [base]/metadata with.
Every FHIR REST server states its capabilities at that path
(https://hl7.org/fhir/R4/http.html#capabilities), so a reachability
question needs no terminology operation. The call is not retried, and
every status is returned as it stands, 401 and 404 included; under
Credentials::OAuth a refused token is renewed once first.
§Errors
Returns Error::BaseUrl when the base URL cannot carry a path,
Error::Token when no token could be obtained, Error::Timeout
when the server did not answer inside the configured budget, and
Error::Transport when the request never reached it.
Sourcepub async fn lookup(
&self,
system: &str,
code: &str,
version: Option<&str>,
) -> Result<LookupOutcome, Error>
pub async fn lookup( &self, system: &str, code: &str, version: Option<&str>, ) -> Result<LookupOutcome, Error>
Resolves the display of code in system.
A server that does not know the code answers LookupOutcome::NotFound
carrying its OperationOutcome; the display is never an empty string.
§Errors
Returns Error::Refused when the server refused the operation for
another reason, and Error otherwise when the call did not reach an
answer or the answer could not be decoded.
Sourcepub async fn lookup_at(
&self,
system: &str,
code: &str,
version: Option<&str>,
date: &str,
) -> Result<LookupOutcome, Error>
pub async fn lookup_at( &self, system: &str, code: &str, version: Option<&str>, date: &str, ) -> Result<LookupOutcome, Error>
Resolves the display of code in system as the code system stood
on date, a FHIR dateTime sent as the date input
(https://hl7.org/fhir/R4/codesystem-operation-lookup.html).
§Errors
As Client::lookup.
Sourcepub async fn expand(
&self,
expansion: &Expansion,
) -> Result<ExpandOutcome, Error>
pub async fn expand( &self, expansion: &Expansion, ) -> Result<ExpandOutcome, Error>
Expands the value set expansion names, with the page, filter, date
and designations it asks for
(https://hl7.org/fhir/R4/valueset-operation-expand.html).
The answer keeps the nesting of expansion.contains. A value set the
server does not know is ExpandOutcome::NotFound carrying its
OperationOutcome, never an empty expansion.
§Errors
Returns Error::Refused when the server refused the expansion for
another reason, too-costly among them, and Error otherwise when
the call did not reach an answer or the answer could not be decoded.
Returns Error::UnsupportedParameter when the expansion names a
value set version on an STU3 client, and Error::ParameterRange
when offset or count exceeds a FHIR integer; nothing is sent.
Sourcepub async fn subsumes(
&self,
subsumption: &Subsumption,
) -> Result<SubsumesOutcome, Error>
pub async fn subsumes( &self, subsumption: &Subsumption, ) -> Result<SubsumesOutcome, Error>
Tests how the two codes subsumption names relate in their code
system (https://hl7.org/fhir/R4/codesystem-operation-subsumes.html).
§Errors
Returns Error::Refused when the server could not determine the
relationship, for example because it does not know a code, carrying
the OperationOutcome and its tx-issue-type coding, and Error
otherwise when the call did not reach an answer or the answer could
not be decoded. An outcome outside the four codes is
Error::Body.
Sourcepub async fn code_system_count(&self, system: &str) -> Result<u32, Error>
pub async fn code_system_count(&self, system: &str) -> Result<u32, Error>
Returns how many CodeSystem resources the server holds under the
canonical URL system, asked as
GET [base]/CodeSystem?url=<system>&_summary=count
(https://hl7.org/fhir/R4/search.html#summary).
A count of 0 says the server does not serve the code system, which
tells an unknown code from an unserved system after a bare 404 from
Client::lookup.
§Errors
Returns Error::Refused when the server refused the search, and
Error::Body when the answer is not a searchset Bundle stating
its total; Error otherwise when the call did not reach an
answer.
Sourcepub async fn translate(
&self,
translation: &Translation,
) -> Result<TranslateOutcome, Error>
pub async fn translate( &self, translation: &Translation, ) -> Result<TranslateOutcome, Error>
Translates the code translation names, through the concept map,
into the target system and in the direction it names.
url, targetsystem and reverse are each sent only when the
translation sets them, as R4 declares each 0..1
(https://hl7.org/fhir/R4/conceptmap-operation-translate.html).
Every match the server returned is carried with its equivalence, so the
caller decides which ones count;
TranslateOutcome::accepted yields the equivalent and equal ones.
§Examples
A deployment with no terminology server holds no client, and a translation it cannot make is a refusal:
use ferrobridge_term::client::Client;
use ferrobridge_term::outcome::Translation;
let Some(client) = terminology.as_ref() else {
return Err("no terminology server is configured".into());
};
let translation = Translation::new("http://example.org/source", "alpha")
.with_concept_map("http://example.org/ConceptMap/source-to-target");
let outcome = client.translate(&translation).await?;
let Some(translated) = outcome.accepted().next() else {
return Err("no equivalent translation".into());
};
let code = translated.concept.as_ref().and_then(|concept| concept.code.as_deref());
assert!(code.is_some(), "an accepted match names its target code");§Errors
Returns Error::Refused when the server refused the operation, for
example because it serves no such concept map, and Error otherwise
when the call did not reach an answer or the answer could not be
decoded. A refusal is never a missing translation. Returns
Error::UnsupportedParameter when the translation names a concept
map on an STU3 client, whose $translate has no url; nothing is
sent.
Sourcepub async fn validate_code(
&self,
value_set_url: &str,
system: &str,
code: &str,
) -> Result<ValidateOutcome, Error>
pub async fn validate_code( &self, value_set_url: &str, system: &str, code: &str, ) -> Result<ValidateOutcome, Error>
Validates that code from system is a member of value_set_url.
§Errors
Returns Error::Refused when the server refused the operation, for
example because it serves no such value set, and Error otherwise
when the call did not reach an answer or the answer could not be
decoded. A refusal is never an invalid code.
Sourcepub async fn validate(
&self,
validation: &Validation,
) -> Result<ValidateOutcome, Error>
pub async fn validate( &self, validation: &Validation, ) -> Result<ValidateOutcome, Error>
Validates that the coded value of validation is a member of its
value set, in any of the three forms the operation accepts: a code
with its system, version and display, a Coding, or a
CodeableConcept
(https://hl7.org/fhir/R4/valueset-operation-validate-code.html).
§Errors
Returns Error::Refused when the server refused the operation, and
Error otherwise when the call did not reach an answer or the answer
could not be decoded. A refusal is never an invalid code. Returns
Error::UnsupportedParameter when the validation names a value set
version on an STU3 client, whose $validate-code has no
valueSetVersion; nothing is sent.
Sourcepub async fn validate_all(
&self,
validations: &[Validation],
) -> Result<Vec<Result<ValidateOutcome, Error>>, Error>
pub async fn validate_all( &self, validations: &[Validation], ) -> Result<Vec<Result<ValidateOutcome, Error>>, Error>
Validates every one of validations, answering them by position: one
call for one validation, one batch Bundle for several.
An entry the server refused is that entry’s own typed error and leaves
the others alone, as in Client::batch.
§Errors
Returns Error::BatchArity when a batch answer holds a different
number of entries than were sent, and Error otherwise when the
batch itself did not reach an answer or its Bundle could not be
decoded. Returns Error::UnsupportedParameter when one of several
validations names a parameter the configured release does not
declare, and then no entry is sent.
Sourcepub async fn batch(
&self,
requests: &[Request],
) -> Result<Vec<Result<BatchOutcome, Error>>, Error>
pub async fn batch( &self, requests: &[Request], ) -> Result<Vec<Result<BatchOutcome, Error>>, Error>
Sends requests as one batch Bundle and answers them by position.
“The server processes each entry independently” and answers a
batch-response whose entries are “in the same order as the request”
(https://hl7.org/fhir/R4/http.html#transaction), so entry n is the
answer to request n. An entry the server refused is that entry’s own
typed error and leaves the others alone.
§Errors
Returns Error::BatchArity when the answer holds a different number
of entries than were sent, and Error otherwise when the batch
itself did not reach an answer or its Bundle could not be decoded.
Returns Error::UnsupportedParameter when a request names a
parameter the configured release does not declare, and then no entry
is sent.