Versions Compared

Old Version 129

changes.mady.by.user Julie Legendre

Saved on

compared with

New Version 130

changes.mady.by.user Julie Legendre

Saved on

Key

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

...

PositiveFor 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 to the anonymous user - login at : log in to Magnolia first, ; open a new tab on in the same window (using the same session); and then requesting request the REST resource.

Upgrade the browser with add-ons to extend its possibilities to controll control the request.


 

cURL

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

Downloadhttps://curl.haxx.se/download.html
PositiveVery flexible to tailor for tailoring the request (method, request headers, user credentials, etc.and so on). Response can be further processed.
NegativeNot 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 atempt 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.

...

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

Positive

Seamless Seamlessly integrated into the Magnolia UAdmin. Comfortable to use form-based interface.

Negative

The endpoints require specific annotations to make them appear on the swagger Swagger UI tools. Delivery endpoint is not annotated and will does not appear on the swagger Swagger tools. REST request is sent by the user which who logged into Magnolia; cumbersome it is difficult to test with different users.

Starting the

...

Swagger UI tools

Go to Dev > REST Tools.

Multiexcerpt
MultiExcerptNameswagger-start

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 from themagnolia-rest-services module (propertiesv1, commandsv2, nodesv1) and one from the cache-browser-app (cachev1).

Now click Click on one of the links - it will to open a submenu which that shows all supported operations provided by the endpoint.

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

Here is an example for for the nodes endpoint 

Mgnl get
 of the nodes endpoint operation:

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

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

...

Using the delivery endpoint

The Delivery delivery endpoint is the latest a REST API provided by Magnolia out-of-the-box. Use it for obtaining JCR data as JSON. 

Besides In addition to defining security settings - , you must provide YAML-based configuration for the delivery endpoint - otherwise the endpoint can not so that it can serve JSON.

Configuring the delivery

...

endpoint

We will create a light module to provide For the YAML-based configuration of required for the delivery endpoint - let us create a light module.

Within the In your light-modules folder - , which is configured with the property magnolia.resources.dir, see above - create the following structure:

Code Block
define-delivery-endpoint/
└── restEndpoints/
    └── delivery-base-definition.yaml

To You can use this code to start with - the file for the delivery-base-definition.yaml can look like this file:

Code Pro
languageyaml
titledelivery-base-definition.yaml
linenumberstrue
class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
params:
  website:
    depth: 2
    nodeTypes:
      - mgnl:page
      - mgnl:area
      - mgnl:component
    childNodeTypes:
      - mgnl:area
      - mgnl:component
    rootPath: /
    includeSystemProperties: false

To get all the details - please refer to You can find a full explanation on Delivery endpoint API - YAML configuration.

For the time being, you should know note the following thingspoints:

  • Line 3: website is the name of the so called "endpoint prefix" - in . In our case it is also the name of a JCR workspace. We will use the value of the endpoint prefix later on within in the REST request URL.
  • Everything below line 3 in defines the file above defines this endpoint prefix.
  • You can define further more endpoint prefixes.
  • Make sure you only have only one YAML-based endpoint definition.

Reading website content with the delivery endpoint

With the given configuration provided above - , you are ready to send REST requests to your Magnolia instance.

Let us We will fetch the content of the page /travel/about on the website workspace. Have a look at Delivery endpoint API - readNode - to  to understand how to compose the URL. We need:

  • The name of of endpoint prefix => website
  • The relative path of the node - relative to what is defined in the configuration as rootPath: => travel/about

...

Now add the "context" (the name of the webapp), the domain and the protocoll - protocol, and you get this these URLs:

The You can request the first URL, which goes to the public contextinstance, you can request with the browser as the anonymous user (without authentication). For the second request URL, you must authenticate.

To test these URLs with cURL, use the following commands:

...