Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
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 |
Tips | If you want to test on REST resources via 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 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 When using one of Magnolia's preconfigured bundles running on localhost, set the property to 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 After setting the base path, restart Magnolia. Swagger UI tools is in Dev > REST Tools./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
http://localhost:8080/magnoliaAuthor/.rest
.
http://localhost:8080/magnoliaAuthor/.rest
.Node name Value
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 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: