Using the APISource:
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) occupationMeasurement::api()
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:
- Obtain a freetext response from the participant describing their occupation and its tasks.
- Send this freetext response to
/v1/suggestionsto get a list of suggested categories.
- Present this list to the participant for them choose an option. (There should always be the option of indicating that none of the suggested categories fit.)
- If the suggested category has followup questions, retrieve the next
followup question from
/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.)
- Use the code from the picked suggested category alongside the
responses to the followup questions to get the final occupation category
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.
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.