Quark Publishing Platform 2015 February 2019 Update Rest Interface Guide

REST framework

The Quark Publishing Platform REST interface lets you access the Platform's functionality using simple HTTP requests. Rather than having to depend on complex remote access libraries such as RMI and SOAP, you can directly invoke functionality and access resources via HTTP and take advantage of standard HTTP mechanisms for transport, session management, security, and error handling. In response to REST calls, the Platform returns any requested data as XML, HTML, or a binary resource stream. If an error occurs, the Platform returns an XML response with an error message and a complete stack trace.

REST URL pattern used in Quark Publishing Platform is:

http://server:port/rest/service/typeofcall/resource?op=[value]&[parameter 1]=[value1]

For secure access to these requests, the platform server should be configured with SSL. Please refer to the "Enabling SSL for Quark Publishing Platform Web applications" chapter in the System Admin Guide in order to learn how to configure the Platform server with SSL.

Request parameters, including op are not required for all calls.

The REST framework is extensible, so you can expose custom services over HTTP.

REST requests return XML responses (by default) or a binary file. The schema of the XML response is specific to the request. These schemas with examples are available in the "Request parameter formats" chapter.

For all requests that return XML you can add an additional paramater (i.e. view=jsonView) to return json instead of an XML response.

You can also apply formatting to returned XML by passing a view parameter that points to an XSL transformation or a .jsp page that generates HTML from the XML. The following example points to a .jsp page. This example can be used with a request that returns a search result:

http://[server]:[port]/[type of call]?view=thumbnail

This example can be used with a request that returns a search result.

Sample .jsp files are provided in the Quark Publishing Platform application folder at QPP Server/webapps/rest/jsp

Users can add their own .jsp file to this folder.

To use custom XSLT, you need to write a custom bean and specify the path of the XSLT file. The XSLT file can be anywhere. The classpath/file location must be mentioned in the bean definition.

Already defined beans allowing you to view responses using XSLT can be found here:

http://ServerName:ServerPort/rest/service/sessions?view=sessionXsltView

Support for Transit Session by providing QPP sessionId or username, password as request parameters. User can make a request to server without logging-in by adding request parameters loginname, loginpassword in their requests. Value for loginname and loginpassword would be the username and password of the user. Another request parameter qppsessionid can be used by providing valid qpp session id.

Session management with REST interface

The following types of sessions can be managed using the REST interface:

  • Transient sessions - these sessions are not actively managed they are created just for the time period it takes to work on a request.

    Users can receive support for a transient session by providing the Quark Publishing Platform's sessionId, username or password as request parameters. Users can make a request to the server without logging-in by adding loginname and loginpassword as request parameters.

    Values for loginname and loginpassword would be the username and password of the user.

    The request parameter, qppsessionid can be used by providing a valid Platform session id.

  • Stateful sessions

    Create a stateful session by using the Session Management service. A stateful session created with this approach will last for the maximum idle time. The session can be kept alive by using the keepsessionalive request. When working with the session, a user does not need to pass the qppsessionid parameter to all requests for the session just created.

HTTP GET and POST Requests

You access the API and manipulate resources by using standard REST conventions. Each API method is invoked using one of the following HTTP methods:

  • GET - performs a read operation

    GET is for retrieving data. When you use the GET method, the browser encodes form data into a URL. Use the GET method only when the form processing is important.

  • POST - performs a create operation.

    POST can involve storing or updating data. When you use the POST method, form data is passed within the message body.