The jFed REST API is deprecated. If you want to know more, contact the jFed developers.

jFed REST API

What is the jFed REST API?

The jFed REST API provides access to the jFed client functionality through a REST API. A demo site is included, which demonstrates the functionality of the API.

The API allows retrieving user and slice info, and setting up experiments (= “creating slivers at one or more AM’s”).

Internally, the jFed REST API uses the same client code of the jFed Experiment GUI.

The REST API uses “speaks for”. This means it calls the needed AM’s and authenticates as itself, but it uses the speaksfor credential in order to perform action as another user (“user A” in the example below). This means the authorization always has 2 parts:

  • The jFed REST API user is allowed to speak for user A (speaksfor credential)
  • User A is allowed to perform action X (regular credential allowing user A to do action X)

Build instructions

You can find a tarball of the latest builds here

Use the maven build file (run mvn package).

The files you need will be created in the rest-api/target/ directory. You will need the rest-api-beta-SNAPSHOT.jar and the entire lib/ directory.

Install instructions

Note: for testing purposes, you probably do not need to install this yourself! A publicly accessible demo site is available at https://jfedapi.ilabt.imec.be (You need to use SSL user authentication to access the sire. Please find detailed instructions on that below.)

Software needed:

  • Java 8 with JavaFX
  • Postgres (version >= 9.5 required due to use of “ON CONFLICT”)

Also needed:

  • Public IP
  • Server DNS name matching the public IP

  • Server SSL certificate and private key for the DNS name

    • Note that the REST API requires a working SSL setup with user authentication. It cannot work on plain http or without user authentication. That’s a feature, because… that’s the only way users can be authenticated.
    • This should not be a self signed server certificate! You should get a “real” one. If it is self signed, browsers that access the API will have to be configured to trust the self signed certificate, which is an extra step that each end user would need to perform, and which is different for each browser.
  • Root SSL certificate of trusted authority
  • CRL for both these certificates

  • Minimal X server

    • Nothing graphical is shown, but JavaFX is initialised for non graphical purposes, and that sadly requires a minimal graphical environment.

Steps:

  • Import both certificates to a java keystore and truststore

    • Some usefull commands to do this:
# Convert the server SSL certificate, which is typically a PEM file,
# to something java's keytool can import directly
TMP_SERVER_KEY_P12="${JAVA_DIR}tmp_server.p12"
openssl pkcs12 -export -in "${SERVER_CERT_FILE}" -inkey "${SERVER_KEY_FILE}" \
    -passout "pass:${TMP_PASS}" \
    -out "${TMP_SERVER_KEY_P12}" -name 'jfedapiserver' \
    -CAfile "${INTERMEDIATE_CERT_CHAIN_FILE}" -caname root -chain

# create the keystore
keytool -importkeystore -deststorepass "${JAVA_KEYSTORE_PASS}" \
    -destkeypass "${JAVA_SERVER_KEY_PASS}" -destkeystore "${JAVA_KEYSTORE_FILE}" \
    -srckeystore "${TMP_SERVER_KEY_P12}" -srcstoretype 'PKCS12' -srcstorepass "${TMP_PASS}" \
    -alias 'jfedapiserver'

# In the config.yml use "jfedapiserver" as certAlias

rm -f "${TMP_SERVER_KEY_P12}"

# Create the trust store containing the root cert of the trusted user and slice authority
keytool -import -alias trustedauthority -file "${TRUSTED_AUTHORITY_ROOT_CERT}" \
    -keystore "${JAVA_TRUSTSTORE_FILE}" -storepass "${JAVA_TRUSTSTORE_PASS}" \
    -noprompt

# Add the chain of intermediate certificate of the server SSL certificate.
# This is probably not needed, but this never hurts.
keytool -import -alias jfedapiserver_chain -file "${SERVER_INTERMEDIATE_CERT_CHAIN_FILE}" \
    -keystore "${JAVA_TRUSTSTORE_FILE}" -storepass "${JAVA_TRUSTSTORE_PASS}" \
    -noprompt

# Show the resulting key and truststore
keytool -list -keystore "${JAVA_KEYSTORE_FILE}" -storepass "${JAVA_KEYSTORE_PASS}"
keytool -list -keystore "${JAVA_TRUSTSTORE_FILE}" -storepass "${JAVA_TRUSTSTORE_PASS}"

  • Create the dropwizard yml config

    • Start from the example config in jfed-rest-api-TEMPLATE.yml

  • Run database migration to create the needed DB tables

    • java -jar <rest-api.jar> db migrate <config.yml>

  • Run jFed REST API server

    • java -jar <rest-api.jar> server <config.yml>

Tips for a clean server setup:

  • Use a systemd unit file to start the server
  • Save log output somewhere (systemd should handle this)
  • Don’t run as root (use setcap to allow privileged ports)
  • Use Xvfb to avoid the need for a screen and graphical setup
  • Use a testing and production version, with a seperate yml file and database.
  • Make sure CRL gets updated automatically, dropwizard doesn’t start when the CRL is expired

Using your wall2 login from your browser

You can make your browser use your wall2 login PEM file, which it will use to authenticate itself using SSL user authentication.

Basic instructions:

  • Login to the iLab.t authority and click “Download PKCS12 version of your certificate”.

  • Now import this certificate into your OS/Browser:

    • For Windows users using Chrome or Internet Explorer : double click the p12 file and install it on your OS.
    • For MAC users using Safari : double click the p12 file and install it on your OS.
    • For Firefox users (Windows, Linux, MAC) : in Firefox, go to Options > Advanced > Certificates and click on View Certificates. Now click Import and browse to the location of your p12 certificate and import it.