How to create a NIF based web service

Michael Röder edited this page Dec 14, 2015 · 2 revisions

To benchmark an annotator using GERBIL we recommend to implement your annotator as NIF-based web service.


The communication between GERBIL and your web service is done using HTTP. Every document that should be annotated by your web service, will be sent inside a single POST request. The body of the request contains the NIF document as RDF data.

The serialization of the RDF should be present in the content header of the request. Currently, only Turtle (application/x-turtle) is supported. Note that the same serialization is expected inside the response.

Example using gerbil.nif.transfer

As a very simple example for such a web service, we created the SpotWrapNifWS4Test project branch. In this branch, a client of DBpedia Spotlight is wrapped as NIF-based web service using our gerbil.nif.transfer library. However, it might be helpful to see how such a web service might work. The important part of this example is the class. It contains the parsing of the request and the generation of the response. The important steps are the following.

        Reader inputReader;
        // 1. Generate a Reader, an InputStream or a simple String that contains the NIF
        // send by GERBIL
        // 2. Parse the NIF using a Parser (currently, we use only Turtle)
        TurtleNIFDocumentParser parser = new TurtleNIFDocumentParser();
        Document document;
        try {
            document = parser.getDocumentFromNIFReader(inputReader);
        } catch (Exception e) {
            LOGGER.error("Exception while reading request.", e);
            return "";
        // 3. use the text and maybe some Markings sent by GERBIL to generate your Markings 
        // (a.k.a annotations) depending on the task you want to solve
        // 4. Add your generated Markings to the document
        document.setMarkings(new ArrayList<Marking>(client.annotateSavely(document)));
        // 5. Generate a String containing the NIF and send it back to GERBIL
        TurtleNIFDocumentCreator creator = new TurtleNIFDocumentCreator();
        String nifDocument = creator.getDocumentAsNIFString(document);
        return nifDocument;

Note that this example uses our gerbil.nif.transfer library. The Markings like named entities that can be added to the document can be found here.