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.
|Positive||For instance Firefox displays JSON and XML in a very readable format.|
A browser provides only limited control to tailor a request without further add-ons. Requests are sent as
If you want to test on REST resources via
Upgrade the browser with add-ons to extend its possibilities to control the request.
cURL is a command line tool. It can be used on most well-known operating systems.
|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.|
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.
Seamlessly integrated into the Magnolia Admin UI. Comfortable to use form-based interface.
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.
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).
Add the following snippet to the pom file of your webapp:
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-tools</artifactId> <version>2.1.3</version> </dependency>
With a downloaded bundle
If you are running a preconfigured Magnolia Tomcat bundle:
- Stop the Tomcat server.
- Download the REST tools bundle magnolia-rest-tools.zip.
- Unzip the download and copy* all the files to:
$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
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.
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 the
magnolia-rest-services module (propertiesv1, commandsv2, nodesv1) and one from the
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: