Getting started with REST

This page is intended for user which want to start the Magnolia REST features. We will show how to setup Magnolia in order to use all the REST functions provided my Magnolia. We quickly explain the available REST endpoints. And we give you an idea how you can test and use these endpoints.

Short version - all in 10' 

This section is a brief summary of the most important things from the sections below. Here we will not go into details but mention the most important points. 

• Get a preconfigured Magnolia bundle with version 5.6 or higher and start the bundle.

Setup

We assume you are using Magnolia bundle with version 5.6 or higher and you know how you can:

• Install Magnolia
• Set the magnolia.resources.dir property in the magnolia.properties file
• Start Magnolia

 Please make sure you have one common directory for the magnolia.resources.dir on both webapps magnoliaAuthor and magnoliaPublic.  If you are unsure how to do that, please refer to the beginners tutorial Hello Magnolia, or use Magnolia CLI - jumpstart with the -p option (to download a bundle and to set a common path for the magnolia.resources.dir all with one command).

Required modules

These three modules listed below are required to use all Magnolia REST features within a productive context. 

• magnolia-rest-integration
• magnolia-rest-services
• magnolia-rest-content-delivery

When using a preconfigured preconfigured Magnolia bundle - your webapp(s) already contain(s) these three modules. When using a custom webapp or bundle, make sure your custom setup contains the  module listed above. See REST module - Installing if you need help to install the Magnolia REST modules.

While developing new features, it can be helpful to use the magnolia-rest-tools which enable the swagger UI tools. Have a look at the next section.

Enabling swagger UI tools

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.

If you do not want to usw the swagger tools- skip the next sections and proceed with testing the setup

Install the module

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

If you are running a preconfigured Magnolia Tomcat bundle:

• Stop the Tomcat server (if it was alrewady started).
• Download the Rest tools bundle 

  Error rendering macro 'artifact-resource-macro'

  com.sun.jersey.api.client.ClientHandlerException: java.net.NoRouteToHostException: No route to host (Host unreachable)

If you have a custom webapp habdling your dependency management with Maven, add the folowwing snippet to the pom file of your webapp:

Set the Swagger API base path

..

<TODO: add more here ...>

Security settings

...

 Testing the setup

...

The endpoints - an overview

...

My first REST request

..

Getting familiar with tools