Using the WSI

This page shows you how to use the RESTful Web Service Interface of your project, or more specifically, its Key Manager Service module.

Starting the WSI

The Key Manager Service module is designed to be embedded in a WAR file which gets deployed to a Servlet container like Apache Tomcat. Therefore, this module does not provide a standalone JAR. For testing purposes, there is a main class which runs a simple HTTP server with the embedded WSI. You can start it using the following command:

$ mvn compile exec:java -Dexec.mainClass=${package}.keymgrsrv.Main \
    -Dexec.classpathScope=test -pl *-keymgrsrv

Installing a License Key

Once the server is running, you can install the license key which you may have generated when using the CLI like this:

$ curl -v http://localhost:9998/license --data-binary @product.lic
* Hostname was NOT found in DNS cache
*   Trying ::1...
* Connected to localhost (::1) port 9998 (#0)
> POST /license HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
> Content-Length: 334
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 334 out of 334 bytes
< HTTP/1.1 204 No Content
< Date: Tue, 10 Mar 2015 23:57:08 GMT
< Content-type: application/json
< Content-length: 0
<
* Connection #0 to host localhost left intact

Note that @product.lic references the license key file which has been previously generated.

The server responds with the status code 204 to indicate that the operation succeeded with an empty response entity.

Loading the License Key

You can load the installed license key using:

$ curl -v http://localhost:9998/license
* Hostname was NOT found in DNS cache
*   Trying ::1...
* Connected to localhost (::1) port 9998 (#0)
> GET /license HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Mar 2015 00:00:04 GMT
< Transfer-encoding: chunked
< Content-type: application/json
<
* Connection #0 to host localhost left intact
{"consumerAmount":1,"consumerType":"User","extra":null,"holder":"CN=Unknown","info":null,"issued":1365757359390,"issuer":"CN=Company Inc.","notAfter":null,"notBefore":null,"subject":"Product 1"}

The server responds with the status code 200 and sends a JSON representation of the license bean which is encoded in the installed license key.

Instead of JSON, you can ask for an XML representation using:

$ curl -v http://localhost:9998/license --header 'Accept: application/xml'
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 9998 (#0)
> GET /license HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: application/xml
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Mar 2015 00:49:59 GMT
< Transfer-encoding: chunked
< Content-type: application/xml
<
* Connection #0 to host localhost left intact
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><license><consumerAmount>1</consumerAmount><consumerType>User</consumerType><holder>CN=Unknown</holder><issued>2015-03-11T01:44:40.608+01:00</issued><issuer>CN=Company Inc.</issuer><subject>Product 1</subject></license>

If no license key is installed, then the server responds with the status code 404 and sends the exception message:

$ curl -v http://localhost:9998/license
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 9998 (#0)
> GET /license HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
>
< HTTP/1.1 404 Not Found
< Date: Wed, 11 Mar 2015 00:12:51 GMT
< Transfer-encoding: chunked
< Content-type: text/plain
<
* Connection #0 to host localhost left intact
java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".

Verifying the License Key

You can verify the installed license key using:

$ curl -v http://localhost:9998/license?verify=true
* Hostname was NOT found in DNS cache
*   Trying ::1...
* Connected to localhost (::1) port 9998 (#0)
> GET /license?verify=true HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Wed, 11 Mar 2015 00:02:53 GMT
< Transfer-encoding: chunked
< Content-type: application/json
<
* Connection #0 to host localhost left intact
{"consumerAmount":1,"consumerType":"User","extra":null,"holder":"CN=Unknown","info":null,"issued":1365757359390,"issuer":"CN=Company Inc.","notAfter":null,"notBefore":null,"subject":"Product 1"}

The server responds with the status code 200 and sends a JSON representation of the license bean which is encoded in the installed license key.

If no license key is installed, then the server responds with the status code 404 and sends the exception message:

$ curl -v http://localhost:9998/license?verify=true
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 9998 (#0)
> GET /license?verify=true HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
>
< HTTP/1.1 404 Not Found
< Date: Wed, 11 Mar 2015 00:15:15 GMT
< Transfer-encoding: chunked
< Content-type: text/plain
<
* Connection #0 to host localhost left intact
java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".

If a license key is installed, but the encoded license bean is invalid, then the server responds with the status code 402 and sends the exception message:

$ curl -v http://localhost:9998/license?verify=true
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 9998 (#0)
> GET /license?verify=true HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
>
< HTTP/1.1 402 Payment Required
< Date: Wed, 11 Mar 2015 00:18:43 GMT
< Transfer-encoding: chunked
< Content-type: text/plain
<
* Connection #0 to host localhost left intact
License validity period has expired at Mittwoch, 11. Februar 2015 16:20 Uhr MEZ.

Uninstalling the License Key

You can uninstall the license key using:

$ curl -v http://localhost:9998/license -X DELETE
* Hostname was NOT found in DNS cache
*   Trying ::1...
* Connected to localhost (::1) port 9998 (#0)
> DELETE /license HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
>
< HTTP/1.1 204 No Content
< Date: Wed, 11 Mar 2015 00:05:28 GMT
< Content-type: application/json
< Content-length: 0
<
* Connection #0 to host localhost left intact

The server responds with the status code 204 to indicate that the operation succeeded with an empty response entity.

If no license key is installed or only an auto-generated FTP license key is installed, then the server responds with the status code 404 and sends the exception message:

$ curl -v http://localhost:9998/license -X DELETE
* Hostname was NOT found in DNS cache
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 9998 (#0)
> DELETE /license HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:9998
> Accept: */*
>
< HTTP/1.1 404 Not Found
< Date: Wed, 11 Mar 2015 00:16:42 GMT
< Transfer-encoding: chunked
< Content-type: text/plain
<
* Connection #0 to host localhost left intact
java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".