README.md 4.67 KB
Newer Older
Rob Tomsick's avatar
Rob Tomsick committed
1
# CRxREST
2

Rob Tomsick's avatar
Rob Tomsick committed
3 4 5 6
**CRxREST** is a modular, RESTful microservice for the search and coding of 
medications.  It provides a model for representing active ingredients, 
products, and associated metadata.  The provided abstraction is designed to 
accommodate multiple, disparate sources of drug information.
7

Rob Tomsick's avatar
Rob Tomsick committed
8 9 10
CRxREST provides a RESTful API for searching for trade names, products, etc.
by both free-form query input as well as by NDC and/or barcode information 
(when supported by the underlying data source.)
11

Rob Tomsick's avatar
Rob Tomsick committed
12 13
The dictionaries/datasets against which CRxREST searches are discovered via an
SPI mechanism and are runtime-configurable.
14

Rob Tomsick's avatar
Rob Tomsick committed
15
## Concepts
Rob Tomsick's avatar
Rob Tomsick committed
16 17 18 19 20 21 22

The CRxREST model is thoroughly documented within the 
`edu.unc.cscc.crxrest.model` package.

#### Dictionaries

Drug and product information within CRxREST is obtained from `Dictionary`s.  
23 24 25 26
A dictionary generally corresponds to an external dataset of some form (for
example: the FDA's NDC database).  As the data represented by various datasets
may vary, dictionaries may declare which portions of the CRxREST model they
support.
Rob Tomsick's avatar
Rob Tomsick committed
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45

The underlying data for a `Dictionary` may come from any source that the 
implementer wishes (e.g. a local file, a remote database.)

#### Dictionary Providers

At the core of the CRxREST module system is a dictionary provider.  A 
dictionary provider is responsible for providing service(s) which may search 
for results within a dictionary. A provider must implement the 
`DictionaryProvider` interface (or one of its sub-interfaces).  In addition,
in order to be eligible for run-time loading, the implementation must be 
annotated with the `@Discoverable` annotation.

### Example Dictionary Provider

The sub-module `ndc-dictionary` serves both a means of supporting the FDA's
NDC dataset and as an example of a dictionary + provider implementation.


Rob Tomsick's avatar
Rob Tomsick committed
46
## Configuration
Rob Tomsick's avatar
Rob Tomsick committed
47

48 49 50
All configuration properties are documented within
`src/main/resources/application.yml`.  Parameters may be set at
run-time like so:
Rob Tomsick's avatar
Rob Tomsick committed
51 52 53 54 55 56 57 58 59

`java -jar path/to/app.jar --crxrest.database.pool-size=2`


Dictionary providers may have their own configuration options.  As CRxREST 
does not mandate a particular configuration scheme for providers you should
consult the documentation of the provider(s) in question for information on 
how to configure them.

60 61 62 63
## API Documentation

OpenAPI documentation will be generated as part of the build process for 
CRxREST.  The resulting documentation will be placed within the `api-docs` 
Rob Tomsick's avatar
Rob Tomsick committed
64
directory.
65

66 67 68 69 70
Included in the same directory is an HTML file providing the
[ReDoc](https://github.com/Rebilly/ReDoc) viewer.  Unfortunately due to flaw
in the JSON Schema design, the viewer will not be able to load the spec from
the filesystem.  Instead, to view the documentation locally you will have to
launch a web server which will serve the `api-docs` directory.  Yes, really.
71

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
## Barcode Search

Currently CRxREST supports UPC-A barcodes.  In an attempt to make this support
more useful, CRxREST is able to use these barcodes to attempt a search against
dictionaries which do not have support for barcodes, but do support NDCs.

UPCs beginning with a `3` (aka UPN) will have their payload extracted, and 
three possible (partial) NDCs created from the resulting data.  These will 
then be used to search the dictionary by NDC for possible matches.

Unfortunately, as it is impossible to determine the grouping form (5-4-2, 
4-4-2, etc.) from a 10-digit without dashes, the exact NDC cannot be 
determined.  The ambiguity therefore means that this approach may produce 
unrelated results.  Due to this possibility, this approach is disabled by
default for the barcode search endpoint (it may be enabled via a request 
parameter, and even then will only be used if an exact UPC match was not 
found.)  It is, however, enabled by default for the "all-in" search (but may 
be disabled by request parameter).

91 92 93
Note that this approach will only yield results if the dictionary service is
capable of dealing with partial NDCs.

Rob Tomsick's avatar
Rob Tomsick committed
94
## Errata
Rob Tomsick's avatar
Rob Tomsick committed
95

96 97
### SPI

Rob Tomsick's avatar
Rob Tomsick committed
98
Only one instance of a given implementation of `DictionaryProvider` may be 
99
handled by CRxREST.  The rationale for this is the same as for Java's native
100 101 102 103 104 105
SPI mechanism.

### Documentation

Due to a flaw in `swagger-core`, there appears to be no way to properly 
represent an empty body for those API operations that produce no content.  
106 107 108
According to the generated API spec, such operations appear to produce an
empty object.  In reality they do not.  Therefore, whenever an API operation
is documented as returning a 204 (No Content) status code, do not expect a
109 110 111 112
response body to be present.  None will.


(This has been [reported to the swagger-core developers](https://github.com/swagger-api/swagger-core/issues/2446), but as of this writing no fix has been provided.)