Tools to test REST requests

In this page, we suggest some tools you can use to test the REST API without needing to develop a REST consuming client application. Testing your REST requests is useful when you are developing client apps and similar things that interact with the REST endpoints.

Browsers

Positive	For instance Firefox displays JSON and XML in a very readable format.
Negative	A browser provides only limited control to tailor a request without further add-ons. Requests are sent as `GET` and you cannot add more request headers out of the box.
Tips	If you want to test on REST resources via `GET`, which requires authetication to get assigned roles not provided to the `anonymous` user: log in to Magnolia first; open a new tab in the same window (using the same session); and then request the REST resource. Upgrade the browser with add-ons to extend its possibilities to control the request.

Browser add-ons

RESTed (Firefox)
Advanced REST client (Chrome app)

cURL

cURL is a command line tool. It can be used on most well-known operating systems.

Download	https://curl.haxx.se/download.html
Positive	Very flexible for tailoring the request (method, request headers, user credentials, and so on). Response can be further processed.
Negative	Not everybody likes command line tools. The response is not easy to read without further tooling. No out-of-the-box automatic URL encoding.
Tips	On the first attempt of a request, use the `-i` option to display all response headers. If the response body is fine and delivers JSON, pretty-print and colorize the response body with tools such as jq.

Swagger UI tools

To use Swagger UI tools, you must install and configure the magnolia-rest-tools submodule. gger UI tools, skip this section or see how to enable the swagger tools above.

Positive	Seamlessly integrated into the Magnolia Admin UI. Comfortable to use form-based interface.
Negative	The endpoints require specific annotations to make them appear on the Swagger UI tools. Delivery endpoint is not annotated and does not appear on the Swagger tools. REST request is sent by the user who logged into Magnolia; it is difficult to test with different users.

The Swagger framework is supported by a set of core tools for designing, building, and documenting RESTful APIs.
Source: https://swagger.io/tools/

Magnolia provides integration with Swagger tools directly in the Admin UI.

Swagger tools are for development and testing purposes only.

Installing the magnolia-rest-tools module

To enable Swagger you must add magnolia-rest-tools to your webapp(s).

With Maven

Add the following snippet to the pom file of your webapp:

<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-tools</artifactId>
</dependency>

With a downloaded bundle

If you are running a preconfigured Magnolia Tomcat bundle:

Stop the Tomcat server.
Download the REST tools bundle.
Unzip the download and copy* all the files to:
- $tomcat/webapps/magnoliaAuthor/WEB-INF/lib
- $tomcat/webapps/magnoliaPublic/WEB-INF/lib (if the directory already exists)

* The zip file may contain .jar files which are already present in the WEB-INF/lib folder of your webapps.

Setting the Swagger API base path

The Swagger API explorer tool searches for the API at a path set in /modules/rest-tools/config/apiBasepath. The default value is http://localhost:8080/.rest. The value for this property must match the following pattern:

<protocol>://<hostname>:<port>/<context>/.rest

When using one of Magnolia's preconfigured bundles running on localhost, set the property to http://localhost:8080/magnoliaAuthor/.rest.

Set the path to where REST services reside on your system. If you run the standard Magnolia bundle and work on the author instance, set the path to http://localhost:8080/magnoliaAuthor/.rest.

Node name	Value
modules
rest-tools
config
apiBasepath	http://localhost:8080/magnoliaAuthor/.rest

After setting the base path, restart Magnolia.

Swagger UI tools is in Dev > REST Tools.

Starting the Swagger UI tools

Go to Dev > REST Tools.

When you open the the Magnolia REST Tools app, you should see something similar to this screen:

The Swagger UI lists the bundled endpoints which already have Swagger annotations. These are the endpoints from themagnolia-rest-services module (propertiesv1, commandsv2, nodesv1) and one from the cache-browser-app (cachev1).

Click on one of the links to open a submenu that shows all supported operations provided by the endpoint.

Click List operations or Expand operations to get the details for the operations.

Here is an example for the nodes endpoint GET operation:

Enter values at least for the mandatory parameters and click Try it out!.

Swagger shows the response code, the response headers and the response body:

Page tree