Versions Compared

Old Version 121

changes.mady.by.user Christoph Meier

Saved on

compared with

New Version 122

changes.mady.by.user Christoph Meier

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 enabling swagger UI tools.

...

Expand
titleClick here to expand to see the step by step procedure

#1 Get the shell and choose a directory to work with

Open a shell and change to directory of your choice. In our example, we use the directory ~/dev/mgnl-rest-test-base.

Code Block
languagebash
cd ~/dev/mgnl-rest-test-base

#2 Downloading a bundle with CLI jumpstart

Code Block
languagebash
mgnl jumpstart

Jumpstart downloads and extracts the latest version of magnolia-community-demo-bundle which comes with Tomcat server. Use the -e option to get the magnolia-enterprise-pro-demo-bundle - which will prompt for enterprise credentials. See jumpstart for further options.

Jumpstart also sets the property magnolia.resources.dir in the file magnolia.properties - which is fine.

When the execution of jumpstart is done, your directory looks like this:

Code Block
mgnl-rest-test-base/
├── apache-tomcat
├── light-modules
└── magnolia.zip

We will need the light-modules folder later on. Please do not start the tomcat so far.

#3 Adding the magnolia-rest tools to the bundle

 Download the Rest tools bundle 

Artifact resource link
groupIdinfo.magnolia.rest
artifactIdmagnolia-rest-tools
label$artifactId.zip
renderTypedownload_link
versionSNAPSHOT
resourceTypeZIP
into a temporary folder. Unzip it. Copy all the files of the unzipped folder into ~/dev/mgnl-rest-test-base/apache-tomcat/webapps/magnoliaAuthor/WEB-INF/lib. Some of the files may already be there, that's fine.

#4 Start Magnolia

You are ready to start Magnolia - actually the Tomcat server - for the first time. Go to our "root" directory ans start with and execute the CLI command start:

Code Block
cd ~dev/mgnl-rest-test-base
mgnl start

Give Magnolia some time. On the first start up Magnolia installs some configurations for a bunch of modules, etc. pp.lot of configuration data and demo content bootsrapped with its modules.

#5 Login on the author context

Open your favorite browser, open the URL http://localhost:8080/magnoliaAuthor/ and login as user superuser with the password superuser. Now you are nearly done. Play around a little bit with Magnolia. Also go to the public context with the URL http://localhost:8080/magnoliaPublic/.

#6 Set the swagger base api path

In order to properly use the swagger UI tools - which are used for development only - we must adapt one property in the configuration.

On the UAdmin - open the Configuration app and open the node /modules/rest-tools/config. (You can use the URL http://localhost:8080/magnoliaAuthor/.magnolia/admincentral#app:configuration:browser;/modules/rest-tools/config:treeview: to go there directly.)

Open the folder config and edit the property apiBasepath. Give it the value http://localhost:8080/magnoliaAuthor/.rest .

This property is one of the rare one which requires a server restart to make the change effective.

#7 Restart Magnolia

Go to the shell where you have started Magnolia.

To stop the server - press cmd + C (on a mac) or ctrl + C (on Windows). Give the server some time to properly shutdown.

Now start it again:

Code Block
cd ~dev/mgnl-rest-test-base
mgnl start


...

Using superuser on the author context - for testing reasons only!

On the author context use the superuser is granted:

...

Note that superuser is given a lot of power. Use it carefully in the context of this tutorial.  But never use superuser on a productive environment for REST.

Using anonymous user on the public context

...

If you want to use REST to create, update and delete content - we recommend using the Nodes endpoint which supports all required operations. If you mainly want to read data - consider using the Delivery endpoint. It provides a very handy formatted JSON and can be customized and configured with YAML via light module. With the Commands endpoint you can trigger commands. And <TODO: Add link to: Cache endpoint> deals Cache endpoint deals with cache.   And you always can create ypur your own custom endpoints - for inspiration see How to create a custom Java based REST endpoint. 

...

cURL is a command line tool. It can be used on most of the well known operating systems. In this tutorial we will often test REST request via cURL.

Downloadhttps://curl.haxx.se/download.html
PositiveVery flexible to tailor the request (method, request headers, user credentials, etc.). Response can be further processed.
NegativeNot everybody likes command line tools. The response is not reasy easy to read without further tooling. No out of the box automatic URL encoding.
Tips

On the first atempt 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.

...

If you have not installed magnolia-rest-tools with the swagger UI tools, skip this section, or see above about ho how to enable the swagger tools.

...