Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
133 lines (103 sloc) 9.45 KB

REST Assured Demo Project...

This project is the Apache Wink Demo for the ICONUK 2016 session. Refer to the slidedeck for further info.

This source repository contains two plugins. The contacts demo and the template plugin. This guide will outline basic steps to install these plugins and how to create your first Apache Wink plugin from the template.


Setting up Eclipse IDE

Wink Demo Plugin

Wink Demo plugin (project name: com.developi.wink.demo) is a sample Apache Wink plugin with several resource implementations. It uses David Leedy's Fake Names database for sample data.


  • Fake names database is in the repository. Extract and put the NSF into your Domino server. Demo plugin uses RestAssured/fakenames.nsf path for the database which might be modified in the DominoAccessor class.
  • In Eclipse IDE, you can import the project directly from Github.
    • Click File\Import, select Git\Projects and click Next.
    • Select Clone URI from the list of options.
    • Enter URI:
    • Click Next
    • Make sure Master branch selected, click Next.
    • Change the local directory if you want. Click Next (It will download the repository now).
    • Select Import existing projects option and click Next.
    • Select com.developi.wink.demo project only for now. The other project will be imported later.
    • Click Finish.
  • Now projects will be seen in the Package explorer. There should be no compile errors ef everything is OK.
    • If there is any compile error with lotus.domino.* classes, you may need to update JRE setting for plugins. It needs to have Notes.JAR file to compile in the class path. XPages SDK installs a local JVM from Domino server installation and plugin has been configured to use it. Check Eclipse SDK configuration steps in case.

Running Plugin on the server:

  • Open Run\Run Configurations in the Eclipse IDE
  • Right click on OSGi Framework and select New
    • Name the new Run configuration (e.g. DominoWeb)
    • Make sure Domino OSGi Framework selected as the Framework
    • In the bundle list, only one plugin needs to be selected for the demo. Deselect All and select com.developi.wink.demo plugin.
    • Click Run.
    • Eclipse will now confirm the Domino directories. Click OK.
      • When properly configured, Eclipse will create a little file in Domino OSGi workspace. Using this file, HTTP task will look for your Eclipse workspace for plugins to be installed.
    • Restart HTTP server on Domino server (use restart task http)
      • Every time you make a change in the plugin code, you need to restart the HTTP server.
      • Tip: You may define an External Tool configuration within Eclipse and bind a key for that. The command to run is c:\IBM\Domino\nserver.exe -c "res task http"

Sample REST services:

Method Service Name Parameters Notes
GET /twink/test N/A Open with browser, returns the effective user name or force authentication.
GET /twink/v1/ping N/A Versioning example
GET /twink/v2/ping N/A Versioning example
GET /twink/contacts start=int count=int Returns a JSON list of contacts
POST /twink/contacts N/A Accepts JSON or Multipart Form Data (not implemented). Saves a new contact document.
GET /twink/contact/{id} N/A Returns a JSON representation of a specific contact by ID
GET /twink/contacts/search q=String FTSearch for a string within contacts, returns a JSON list.

Using template plugin to create your own Wink Project

The second project in the repository is the template project to start your first Wink plugin quickly.

  • In Eclipse menu, File\Import and select General\Existing projects into Workspace. Click Next.
  • Click Browse for Select root directory and pick the root of the Git repository directory you have cloned.
    • By default, it will be C:\Users\<your windows username>\git\RestAssuredDemo
  • You should only be able to select com.developi.wink.template project now.
  • Make sure you ticked Copy projects into workspace option. Otherwise, it will be linked to the Git repo.
  • Click Finish.
  • Now you will have a new copy of the template project. It is located inside your Eclipse Workspace.
    • You can move it to any folder you want (e.g. your own Git repo) by right click on the project and Refactor\Move.
    • You can rename it by Refactor\Rename. (I will use com.acme.restapi name for the guide).
    • Expand src directory and rename the package com.developi.wink.template by right click and Refactor\Rename.
      • New name will be com.acme.restapi. Make sure enable all options on this page. configuration files and subpackages should also be updated.


In plugin.xml file, you will see the servlet definition for Apache Wink. If everything is OK, you will see this content:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
        	<init-param name="DisableHttpMethodCheck" value="true"/>
  • alias is the base URI for your wink project. Domino server will grab all requests under this URI and send them into your Wink plugin. Change this according to your choice of URI.
    • Do not use existing URI's on Domino (e.g. xsp, api, any directory names exist in your data folder)
  • class points into the custom servlet class in the project. You may use this class to inject any code to be run at a servlet-level events. Read comments in the class.
  • applicationConfigLocation points into a text file where resources to be registered are listed. You should add your own resources into this file. One test resource has been added as a sample.

Congratulations! You are now ready to run your first Wink Plugin! Make sure you have enabled this new plugin in your run configuration and restarted HTTP server. Good luck!


Fakenames database has been used with the permission from David Leedy. Also thanks to Fake name Generator as the primary source of all fake names. The names are shared under Creative Commons BY-SA 3.0 US license.