Starting the API is simple, as you will only need to call the
api() method. This will immediately start a local plumber
server and will open a window with the API’s documentation.
# Start the API (and open its documentation) ::api()occupationMeasurement
The API is designed to allow for similar usage as the interactive
application, but implementing the UI and its logic has to be done
manually. It is recommended to use the same text prompts as the shiny
app()) for consistency.
A typical workflow for using the API is as follows:
/v1/suggestionsto get a list of suggested categories.
/v1/next_followup_questionand present it to the user. (It is technically possible to skip this step, but the quality of the final codings would diminish.)
This is the simplest workflow possible; explore the app for our recommended, more respondent-oriented workflows.
Each of the API endpoints comes with a set of options / parameters which are described in the API’s documentation. The API documentation is automatically available when starting the API, comes with the option to test out endpoints and provides example code on how to query the API.
The easiest way of understanding how the API works, is by starting it
api() and exploring the included Swagger
documentation that will open automatically. Using the UI one can
interactively explore different API endpoints, what input they expect
and what output they return.
The api also comes with an openapi specification at
Since the API has multiple endpoints to be called, it expects a certain flow of how requests follow onto each other in order to properly function.
The diagram below demonstrates a minimal version of this flow, with different API endpoints highlighted in bold. More complex scenarios are possible if you e.g. implement multiple tries of generating job suggestions for cases where user input was ambiguous.
Note: This flow assumes that an “auxco”-based suggestion-type is used (the default), which also adds followup questions to be asked to respondents. When using a different suggestion type, such as “kldb-2010” only the “/get_suggestions” endpoint is necessary, but final encodings might be of worse quality.
For inspiration on how to implement the user-facing flow of
an application using the api, take a look at
vignette("app") and refer to the interactive
app() included in this package.
The API comes with a pre-built Docker image for easy deployment on a server, your own computer or the cloud. If you wish to deploy the API without using docker, information on how to deploy a plumber API can be found here.
Note that the
api()function will, by default, immediately start the API instead of returning a plumber instance. If you want to have access to the plumber instance for additional control during deployment, you can get it by calling the API via
api(start = FALSE).
For easy deployment of the app, the package comes with a pre-built
docker image called
To test this image on your local machine you can run the following command in your command line (this assumses you have Docker installed):
# Start the api # it can be reached at http://localhost:8000 # Swagger documentation can be viewed at http://localhost:8000/__docs__/ docker run --rm -p 8000:8000 -v $(pwd)/output:/output -e ALLOW_ORIGIN="*" -e REQUIRE_IDENTIFIER=TRUE ghcr.io/occupationmeasurement/api:latest
For more detailed information on the docker images if you e.g. want to build your own refer to the docker directory in the repository.