npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hisptz/dhis2-mediator

v1.0.8

Published

1. [Introduction](#Introduction)

Downloads

3

Readme

DHIS2 API MEDIATOR

  1. Introduction

  2. Pre-requisites

  3. Getting started with API

    3.1. Installations

    3.2. Configuration

  4. Running the of API

    4.1. Running the development server

    4.2. Building the API

    4.3. Running the production server

  5. How to connect with another application

  6. How to contribute

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.

Flow chart

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.