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