Using the API¶

The Krill API is a primarily JSON based REST-like HTTPS API with bearer token based authentication.

Getting Help¶

Consult the Interactive API documentation (courtesy of ReDoc)
Follow the API links in the Krill CLI documentation, e.g. API Call: :krill_api:`GET /v1/cas <list_cas>`
Check out the API hints built-in to the Krill CLI, e.g.

$ krillc list --api
GET:
  https://<your.domain>/api/v1/cas
Headers:
  Authorization: Bearer *****

Generating Client Code¶

The OpenAPI Generator can generate Krill API client code in many languages from the Krill v0.7.3 OpenAPI specification.3

Sample Application¶

Below is an example of how to write a small Krill client application in Python 3 using a Krill API client library produced by the OpenAPI Generator. To try out this sample you’ll need Docker and Python 3.

1. Save the following as /tmp/krill_test.py, replacing <YOUR XXX> values with the correct access token and domain name for your Krill server. This example assumes that your Krill instance API endpoint is available on port 443 using a valid TLS certificate.

# Import the OpenAPI generated Krill client library
import krill_api
from krill_api import *

# Create a configuration for the client library telling it how to connect to
# the Krill server
krill_api_config = krill_api.Configuration()
krill_api_config.access_token = '<YOUR KRILL API TOKEN>'
krill_api_config.host = "https://{}/api/v1".format('<YOUR KRILL FQDN>')
krill_api_config.verify_ssl = True
krill_api_config.assert_hostname = False
krill_api_config.cert_file = None

# Create a Krill API client
krill_api_client = krill_api.ApiClient(krill_api_config)

# Get the client helper for the Certificate Authority set of Krill API endpoints
krill_ca_api = CertificateAuthoritiesApi(krill_api_client)

# Query Krill for the list of configured CAs
print(krill_ca_api.list_cas())

Run the following commands in a shell to generate a Krill client library:

# prepare a working directory
GENDIR=/tmp/gen
VENVDIR=/tmp/venv
mkdir -p $GENDIR

# fetch the Krill OpenAPI specification document
wget -O $GENDIR/openapi.yaml https://raw.githubusercontent.com/NLnetLabs/krill/v0.7.3/doc/openapi.yaml

# use the OpenAPI Generator to generate a Krill client library from the krill
# OpenAPI specification
docker run --rm -v $GENDIR:/local \
    openapitools/openapi-generator-cli generate \
    -i /local/openapi.yaml \
    -g python \
    -o /local/out \
    --additional-properties=packageName=krill_api

# install the generated library where your Python 3 can find it
python3 -m venv $VENVDIR
source $VENVDIR/bin/activate
pip3 install wheel
pip3 install $GENDIR/out/

Run the sample application:

$ python3 /tmp/krill_test.py
{'cas': [{'handle': 'ca'}]}

Tip

To learn more about using the generated client library, consult the documentation in $GENDIR/out/README.md.

Warning

Future improvements to the Krill OpenAPI specification may necessitate that you re-generate your client library and possibly also alter your client program to match any changed class and function names.