@hisptz/dhis2-mediator
v1.0.8
Published
1. [Introduction](#Introduction)
Downloads
3
Keywords
Readme
DHIS2 API MEDIATOR
3.1. Installations
3.2. Configuration
4.1. Running the development server
4.2. Building the API
1. Introduction
This is NestJS application that act as a mediator between a DHIS2 instance and a front end application for handling authentication and allow whitelisting of DHIS2 API resources. With the help of this mediator, one can expose part of DHIS2 API that could be used by a custom front end application while also ensuring authentication using configurations set.
2. Pre-requisites
- node +12
- npm +6.13
- docker-engine +20.10.11
- docker-compose +1.29.1
- nestjs +7.0.0
3. Getting started with API
3.1. Installations
To clone the app and install all app dependencies, run the below commands
git clone https://github.com/hisptz/dhis2-mediator
cd dhis2-mediator
npm install
3.2. Configuration
There are two types of configurations that need to be done to get the mediator API up and running. These configurations are:
3.2.1 Environmental variables configurations
The environmental variables configurations enables configuration of the DHIS2 instance url, username and password. It also allows setting of the port where the mediator API will be running and both the readonly and allowed resources. This can be done as the .env.example
file.
# DHIS2
DHIS2_BASE_URL="path_to_dhis"
DHIS2_USERNAME="username"
DHIS2_PASSWORD="password"
DHIS2_API_TOKEN="api_token"
PORT="3000"
CACHE_TTL="<number-of-milliseconds-for-caching-readonly-resources>"
NUMBER_OF_REQUESTS_PER_MINUTE="<number-of-client-nrpm-per-minute>"
READONLY_RESOURCES=["resource1"]
ALLOWED_RESOURCES=["resource2"]
NOTE
This could be specified as READONLY_RESOURCES = ["me", "dataElements/XXXXXXXXXX"]
This could be specified as ALLOWED_RESOURCES = [ "trackedEntityInstances", "events"]
This could be specified as CACHE_TTL = 3600
This could be specified as NUMBER_OF_REQUESTS_PER_MINUTE = 100
3.2.2 Docker compose configurations
These configurations are use for starting the docker image from the build. The example of these configurations can be through the docker-compose.example.yml
. Rename the file to or create a copy of this file with name docker-compose.yml
and fill in the configurations as how the file contents suggests.
version: '3.2'
services:
mediator:
container_name: mediator-api
build:
context: .
network: host
image: mediator-api
restart: always
ports:
- '3333:3333'
env_file: .env
networks:
- mediator-api
networks:
mediator-api:
driver: 'bridge'
4. Running the of API
Once all configuration has been done and packages installed, the mediator can now be started either in development or on production mode.
4.1. Running the development server
The development server can be started by running the command:
npm run start
or for a watch mode with
npm run start:dev
or just:
nest start
4.2. Building the API
Building the mediator API, can be done by running the command:
npm run build
This command builds the API into the dist
folder while at the same time moving the .env.example
and docker-compose.yml
files to your dist folder and also creating the api.zip
file that has all the dist
folder contents zipped.
4.3. Running the production server
There are two ways for running the production server, these are:
It should be noted that both of this approaches needs to be done after the building the mediator API
4.3.1 Using Node.
To run the development server with docker, while at the root of the project use the command:
npm run start:prod
4.3.2 Using Docker.
If using the api.zip
file, the file should be first unzipped and navigate into the resulting folder. On the other hand if using the app source code, navigate to the dist folder.
The next step applies to all the above scenarios, and that is creating of .env
file similar to the above configuration instructions.
Lastly to start the production server run the command
docker-compose up -d --build
NOTE
For more configurations of the ports and how docker-compose would be handling the mediator API, make changes on the docker-compose.yml
file.
5. How to connect with another application
Once the mediator is running either on development or production(recommended) mode, other applications can access the
DHIS2 API through this mediator by making HTTP nrpm to the API resources (allowed and readonly) as specified on
the .env
file through the specified port.
# DHIS2
DHIS2_BASE_URL="https://play.dhis2.org/40.0.1"
DHIS2_USERNAME="admin"
DHIS2_PASSWORD="district"
DHIS2_API_TOKEN="d2pat_GqYQTgdx2rzgIGvJhjCuHe70Evh9d7nO2925016161"
PORT="3000"
CACHE_TTL="360000"
NUMBER_OF_REQUESTS_PER_MINUTE=30
READONLY_RESOURCES=["me", "dataStore"]
ALLOWED_RESOURCES=["fileResources", "dataStore"]
Considering the above example of .env
configurations, the API endpoints can be accessed as following:
5.1 Accessing readonly resources
These API resources can only be accessed by a GET HTTP method. As per the above example we can access the me
resource using
GET
curl -v localhost:3000/api/me
<strong>NOTE</strong>: These resources are cached, hence only the first request is sent to the DHIS2 instance. To clear the cache, a DELETE HTTP request should be sent to the endpoint `cache` as:
Clear cache
curl -X DELETE http://localhost:3000/api/cache
### 5.2 Accessing allowed resources
These API resources can only be accessed by GET, POST and PUT HTTP methods. As per the above example we can access the `dataStore` resource using the following nrpm. These resources are not cached, hence no clearing of cache required for these resources.
GET
curl -v localhost:3000/api/dataStore
POST
curl -d '[1, 2, 3]' localhost:3000/api/dataStore/demo/demo-item-1
PUT
curl -d '{"name": "userName", "value": "Megamind"}' -X PUT localhost:3000/api/dataStore/demo/demo-item-1
## 6. <a name='contribute'></a>How to contribute
In order to contribute to this project, fork the repository, make the necessary changes and submit the pull request for review.