REST Interface

The REST interface handles communication between the client application and jadice server via common HTTP requests as well as GET, POST, and DELETE methods. Messages are exchanged in XML or JSON format.

Figure 7.3. Schematic of the REST Interface

The REST interface receives requests via various methods, processes them, and replies in XML or JSON format.

Tip

We recommend soapUI and Postman for developing and debugging REST requests.

Organization of the REST Interface

In order to operate the REST interface, it needs to be activated as described in the section called “Configuring the REST Interface”. It can be reached at http://<hostname>:9001/jadiceServer/. For the purpose of better readability the URL's host name (http://<hostname>:9001) will be omitted in this manual.

The following paragraphs provide a short overview of the methods at your disposal. In the section called “Exemplary Processing Sequence Using REST”, we demonstrate how to build a conversion sequence from these methods.

Integrated Documentation

We provide an integrated documentation for the REST interface in the Open API format (also known as “swagger”). It can be accessed at /jadiceServer/swagger.json in JSON format or at /jadiceServer/swagger.yaml in YAML format.

In addition, you can find an interactive documentation of the REST interface at /jadiceServer/api-docs?url=/jadiceServer/swagger.json. You can launch all available methods directly from the browser:

Figure 7.4. View of Swagger UI

With the help of swagger UI the REST interface can be operated from the browser.


File Service

The File service is responsible for uploading files to be processed by jadice server or to receive resulting files from jadice server. It can be reached at /jadiceServer/files.

It allows for the following methods:

POST to /jadiceServer/files
Uploads a new file. The File service returns an ID ({fileId}) with which you can retreive the file during subsequent steps.
GET from /jadiceServer/files/{fileId}
Downloads a file. Its file name and MIME type will be assigned to the common header fields Content-Disposition and Content-Type.
DELETE from /jadiceServer/files/{fileId}
Deletes a file from the server.

Template Service

The Template service allows you to inquire which job templates are available. Their syntax follows the one described in the section called “Definition of Job Templates” and they can usually be found in the subdirectory /server-config/jobtemplates.

The following methods are available through the Template service:

GET from /templates
Downloads a list of all available job templates. This list contains the IDs with which the individual job templates can be referenced ({templateId}).
GET from /templates/{templateId}
Downloads a specific job template. Since job templates are in XML format, they can not be returned in JSON format.

Job Service

The Job service is used to send conversion requests to jadice server and get updates on their progress. Furthermore, it bundles information on the resulting documents and the log messages generated during processing.

The Job service provides the following methods:

POST to /jadiceServer/jobs
Creates a new Job and immediately initializes its processing. The method returns an ID with which the job can be traced ({jobID}).
GET from /jadiceServer/jobs/{jobId}
Gets information on the current state of the job.
DELETE from /jadiceServer/jobs/{jobId}
Deletes all information on this job from the server. If the job is still being processed, it is automatically aborted.

Exemplary Processing Sequence Using REST

After shortly introducing the individual services offered by the REST interface, this section will illustrate the conversion sequence with the help of an example. Figure 7.5, “Sequence diagram of processing with REST” provides an overview of the sequence in the shape of a UML sequence diagram.

Figure 7.5. Sequence diagram of processing with REST


The following paragraphs offer a verbal description of the conversion process as well as exemplary requests of the client application and the corresponding response by jadice server. JSON format is favored in the examples.

Note

  • HTTP header fields that are irrelevant to understanding the processing sequence have been left out.
  • HTTP header and body have been separated by a blank line in this depiction.
  • To improve readability, the JSON objects have been edited with word wraps and indentions.

  1. Before a job can be dispatched to jadice server, you have to choose the job template which is to be used. In order to find out which job templates are available, the template service is called by using the GET request on /jadiceServer/templates/. Thus, a list of all available templates (respectively their IDs) is returned either in JSON or XML format. If you want to find out about the content of a template, you can download it using the GET request on /jadiceServer/templates/{templateId}.

    Example 7.13. Querying Available Job Templates

    Request Response 
    GET /jadiceServer/templates HTTP/1.1
Host: <hostname>:9001
Accept: application/json
    		 
    HTTP/1.1 200 OK
Content-Type: application/json

{
 "templates": [
  "mail2pdf.xml",
  "one-node.xml",
  "x2pdf.xml"
 ]
}

    Example 7.14. Querying an Individual Job Template

    Request Response 
    GET /jadiceServer/templates/x2pdf.xml HTTP/1.1
Host: <hostname>:9001
Accept: application/xml
    		 
    HTTP/1.1 200 OK
Content-Type: application/xml

<job (...) >
 (...)
</job>

  2. The files that are to be converted are uploaded to the server: each file that is to be processed is uploaded using a POST request with the content type multipart/form-data on /jadiceServer/files. The server returns a file ID with which you can reference the file throughout the process.

    Example 7.15. Uploading a File

    Request Response 
    POST /jadiceServer/files HTTP/1.1
Host: <hostname>:9001
Accept: text/plain
Content-Type: multipart/form-data; boundary=----Boundary-12345

------Boundary-12345
Content-Disposition: form-data; name="file"; filename="my-file.txt"
Content-Type: text/plain

Lorem Ipsum...
------Boundary-12345--
    		 
    HTTP/1.1 201 Created
Content-Type: text/plain

stream-uuid-0001


  3. With the help of these details, a job can then be created and sent to the job service by using a POST request on /jadiceServer/jobs. The service returns a job ID with which the job can be referenced.

    Example 7.16. Initializing a Job

    Request Response 
    POST /jadiceServer/jobs HTTP/1.1
Host: <hostname>:9001
Accept: text/plain
Content-Type: application/json

{
  "templateId": "x2pdf.xml",
  "templateParameters": {},
  "inputFiles": [
    {
      "fileId": "stream-uuid-0001"
    }
  ]
}
    		 
    HTTP/1.1 201 Created
Content-Type: text/plain

job-uuid-0001


  4. The current state of a job can be inquired by using the GET request on /jadiceServer/jobs/{jobId}. You have to wait for the state to be FINISHED. If the job cannot be processed successfully, the conversion concludes in the state FAILED, see also Job.State.

    Example 7.17. Inquiring about the Current State of a Job

    Request Response 
    GET /jadiceServer/jobs/job-uuid-0001 HTTP/1.1
Host: <hostname>:9001
Accept: application/json
    		 
    HTTP/1.1 200 OK
Content-Type: application/json

{
 "templateId":"x2pdf.xml",
 "templateParameters":{},
 "id":"job-uuid-0001",
 "state":"FINISHED",
 "inputFiles":[
  {
   "fileId":"stream-uuid-0001",
   "nodeId":null
  }
 ],
 "resultFiles":[
  {
   "fileId":"stream-uuid-0002",
   "nodeId":"node2"
  }
 ]
}


  5. The generated files, whose file IDs are named in the response of the job service, can be downloaded separately by using a GET request on /jadiceServer/files/{fileId} for each file.

    Example 7.18. Downloading a File

    Request Response 
    GET /jadiceServer/files/stream-uuid-0002 HTTP/1.1
Host: <hostname>:9001
Accept: application/octet-stream
    		 
    HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=my-file.pdf
Content-Description: my-file.pdf

%PDF-1.4...


  6. After processing is finished, all resources which are not required for further conversions, have to be deleted:

    • The uploaded and generated files are deleted using a DELETE request on /jadiceServer/files/{fileId} for each of them.

      Example 7.19. Deleting a File

      Request Response 
      DELETE /jadiceServer/files/stream-uuid-0001 HTTP/1.1
Host: <hostname>:9001
Accept: application/json
      		 
      HTTP/1.1 204 No Content


    • The job is deleted using a DELETE request on /jadiceServer/jobs/{jobId}.

      Example 7.20. Deleting a Job

      Request Response 
      DELETE /jadiceServer/jobs/job-uuid-0001 HTTP/1.1
Host: <hostname>:9001
Accept: application/json
      		 
      HTTP/1.1 204 No Content


    Important

    Deleting jobs and files that are not required anymore is essential since they are not deleted automatically by jadice server and thus may take up much-needed storage space and memory.

Generating REST clients

The Open API specification of the REST interface in cooperation with the command line tool swagger-codegen enable generating a client library that can be used in the desired implementation language. In order to do so, please first download the library swagger-codegen-cli-<version>.jar from http://swagger.io/swagger-codegen/.

You can find out for which languages swagger-codegen can generate client libraries by using java -jar swagger-codegen-cli-<version>.jar: 

Available languages: [android, aspnet5, async-scala, cwiki, csharp, cpprest, dart, flash, python-flask,
go, groovy, java, jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript, javascript-closure-angular,
jmeter, nancyfx, nodejs-server, objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, sinatra,
rails5, slim, spring, dynamic-html, html, html2, swagger, swagger-yaml, swift, tizen, typescript-angular2,
typescript-angular, typescript-node, typescript-fetch, akka-scala, CsharpDotNet2, clojure, haskell, lumen, go-server]

A simple Java client is generated by using this command: 

java -jar swagger-codegen-cli-<version>.jar generate
  --lang java
  --input-spec http://<hostname>:9001/jadiceServer/swagger.json

swagger-codegen offers various options to customize the generated client library. The following example illustrates how to modify output folder and namespaces: 

java -jar swagger-codegen-cli-2.2.1.jar generate
  --lang java
  --input-spec http://<hostname>:9001/jadiceServer/swagger.json
  --output generated-client
  --invoker-package com.acme.invoker --model-package com.acme.model --api-package com.acme.api

Figure 7.6, “Java Project generated by swagger-codegen” shows the classes that are generated as a result.

Figure 7.6. Java Project generated by swagger-codegen

The classes generated with the help of swagger-codegen can be used directly in the IDE.


[jadice server Version 5.8.7.0: Documentation for Developers and Administrators. Published: 2021-04-15]
Prev  Up  Next
  Home