Europeana-Apikeyclient: apikey-service client & demo

This project consists of two parts:

• Apikeyclient: a small library intended to provide a unified and transparent way of validating Apikeys

• Apikeydemo: a Spring Boot & Thymeleaf web-app intended to demonstrate how the Apikeyclient can be used. It can also be run locally for testing purposes.

Apikeyclient

how to use the client

In order to validate an Apikey you need to supply the following parameters:

• adminKey and adminSecretKey (a valid ADMIN level apikey / secretkey pair);

• api (the API for which the apikey needs to be validated: can be search, entity or annotation);

• optionally, method (allowable values: read or write)

These parameters can be either passed directly into the validateApiKey() method of a Connector instance or wrapped in a ValidationRequest object using the usual POJO setters.

Under normal conditions the Connector instance will return a ValidationResult object. The ValidationResult has the following methods:

• isValidKey() (boolean): returns true if there were no errors and the Apikey is valid. false in any other case

• getReturnStatus() (String) returns the HTTP status of the Apikey Service’s response. Possible values are: 204 (apikey valid); 400 (bad Request: missing or wrong parameter(s)); 404 (apikey not found OR Apikeyservice not found ⇒ see isPageNotFound_404); 410 (apikey deprecated) or 429 (request quota reached)

• getRemaining() (Integer): the remaining number of requests left for this period

• getSecondsToReset() (Integer): the number of seconds until the request quota is reset

• getMessage (String): eventual additional error message

• hasConnected (boolean):

• isPageNotFound_404 (boolean): whether a HTTP 404 status is a regular Page not found returned by the webserver, rather than the Apikey not being found by the Apikey Service

Additionally, if there are technical problems that prevent the request from being fulfilled, an ApikeyValidationException will be thrown. The getErrorMessage() method returns a brief (one-line) error message; if needed the underlying Exception (if any) can be retrieved with the getCause() method.

The Apikey Service’s URL is stored as the apikeyserviceurl property in the Apikeyclient’s config.properties file in the resources directory. Its value is set to https://apikey-test.eanadev.org/apikey - the currently deployed Apikey Service test instance on Bluemix.

deployment

Build the client jar by executing mvn clean install - apikeyclient-{VERSION}.jar will be available in the target directory.

Apikeydemo

usage

This is first and foremost intended as a coding example: see the demoSubmit method of the ClientController class.

The Apikeydemo can also be used to test or demo the Apikeyclient and / or Apikey Service with. It is a Spring Boot & Thymeleaf web-app that runs locally on port 8080, path /demo:

http://localhost:8080/demo

It displays a form titled Apikey Service client demo app with three dropdown-lists:

1. Apikey: one to select between a number of test Apikeys that exist in the database of the test Apikeyservice;

2. api: another one to choose between several (Europeana) Api’s, with an empty string and some otherwise erroneous values to test with;

3. method: and one to select the method parameter: read, write, nothing and some other erroneous values.

The demo app uses the Apikeyclient classes to connect to the Apikeyservice and displays the results on a second page. Note that it uses ApiKey1 and SecretKey1 as hard-coded values for adminApikey and adminSecretkey.

deployment and running the demo

Build the demo by executing mvn clean install and run with mvn spring-boot:run. The demo app will be deployed on http://localhost:8080/demo

Requirements

JDK version used: Java 1.8.0.74