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
- Start from the example config in
-
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.