ICD-API in a Container (beta version)

The container version of the ICD-API allows you deploy the API to a local setting. You need to make sure that the location that you deploy the container is not open to public internet.

The container version of the ICD-API is almost the same as the version that is hosted in the cloud at the https://id.who.int/icd/... with the following differences:

1- The actual ICD-API end point URIs start with https://id.who.int/icd . The endpoint URIs of the local containers are the same except for this header. So if you deploy the container at http://yourserver then The main foundation URI https://id.who.int/icd/entity becomes http://yourserver/icd/entity in the container

The API, even when deployed locally, refers to ICD entities with their canonical URIs (i.e. URIs that start with http://id.who.int/icd/...) Therefore, you need to change them to your local API addresses when you use the API from a local installation.

2- The containerized version does not require OAUTH-2 authentication

Installing the docker container

You may use Linux, Mac, Windows 10 or a recent Windows Server to deploy the container.

First you need to install docker. This depends on the operating and therefore we are not providing the details of this. However, it is a fairly a straight forward process.

Once you have docker, you need to run a container with our image.

docker run -p 80:80  whoicd/icd11_sw_1904_mms_en

The docker run command creates a new container and installs the image (this may take some time in its initial run)

Once the container is ready you'll see this screen

 ooooo   .oooooo.   oooooooooo.             .o    .o
  888   d8P    Y8b   888     Y8b          o888  o888
  888  888           888      888          888   888
  888  888           888      888          888   888
  888  888           888      888 8888888  888   888
  888   88b    ooo   888     d88           888   888
 o888o   Y8bood8P   o888bood8P            o888o o888o

Starting ICD-API
Starting ICD-11 Coding Tool

ICD-11 Container is Running!
You need to visit the configuration page (/configure) before starting to use the ICD-API
You may close the shell window or Ctrl-C to return to shell (container will continue to run)

The first thing you need to do at this point is opening the /configure page of the container and fill in the license agreement and consent form.

The form is as follows:

  • [ ] I agree with the license agreement

  • [ ] I agree that this system (the container that is deployed) can send data to WHO on the searches made in order to improve search capability of ICD-11 tools.

  • [ ] I agree that this system (the container that is deployed) can send IP addresses together with the data mentioned above. This is needed in order to understand local terms variations that are used in different places.

[ Save configuration ]

Agreeing with the license terms is required but the other two are optional.

Once the form above is filled and the configuration is saved, you'll get this message.

Configuration is updated. Please wait until the API service is restarted...
ICD-API is configured and ready to use!

At this point your container with the ICD-API is up and running. You may check it by opening the swagger endpoint /swagger/index.html (if your container is deployed at the localhost, this would be http://localhost/swagger/index.html)

Bypassing the configuration user interface

You may provide additional parameters to the docker run command to bypass the configuration screen. It this case the container starts with the provided configuration and there is no need to visit the /configure endpoint.

To do that you need to set 1 mandatory and 2 optional environment variables in the docker run command:

  • acceptLicense (needs to be set to true)
  • saveAnalytics (true or false)
  • includeIp (true or false)

The meanings of these environment variables are the same as the form above

Example of running the container without the need of further configuration:

docker run -p 80:80  --env "acceptLicense=true" --env "saveAnalytics=true" --env "includeIp=false" whoicd/icd11_sw_1904_mms_en