1. Introduction

For a long time, web applications were built as a conglomerate of many static websites. Today, dynamic web applications have established themselves as the industry standard. A typical challenge, which must be mastered again and again during the development of such an application, is the provisioning of a navigation. It is necessary to create a structured connection between human-readable URL paths and the actual content that has to be dynamically loaded from other sources. The application must know what to display depending on the URL.

Until now, this was a task that had to be solved individually for each Web application. Now the Navigation Service provides a standardized format so that solutions can be reused in the future. The developers can concentrate less on technical details and more on the added value of their application.

The Navigation Service is an e-Spirit product that is offered exclusively as a Software-as-a-Service offering in the cloud. Self-hosted instances are not supported.

2. Technical overview

The Navigation Service is a service that facilitates the provisioning of navigations in dynamic (web) applications. For this purpose, it provides a REST API, which can be used to save navigations in a suitable format in the Navigation Service and to read them out again later. They can be retrieved in their entirety or filtered in suitable ways. The chapter Features explains the individual functions of the Navigation Service in detail.

2.1. Typical use cases

The Navigation Service is to be regarded as part of the delivery layer. In the classic scenario, the first step is to persist a navigation in Navigation Service. The URL where this navigation is now accessible has to be persisted in a dynamic (web) application. Each time the application is called, it retrieves the navigation from the Navigation Service and is then able to display the correct content to the user.

In the FirstSpirit universe, the persistence and updating of navigations in Navigation Service is handled by the Navigation FirstSpirit module. This allows editors to modify content in FirstSpirit, after which the changes are automatically reflected in the navigation. This way, new content can be displayed in applications without having to change the applications themselves.

2.2. OpenAPI specification

OpenAPI specification is a standard for describing REST compliant programming interfaces. The Navigation Service provides an OpenAPI specification including the following resources:

2.3. Format of a navigation

All communication with the Navigation Service takes place in JSON. Primarily, navigations are either queried or persisted. Navigations are represented as a tree, with each element of the tree representing a navigation element.

Example navigation
{
    "id": "815c307c-2ca6-4f02-9653-fa3454988fc2",
    "label": "products",
    "seoRoute": "/products",
    "seoRouteRegex": null,
    "contentReference": "/Products/Sales/index.html",
    "visible": true,
    "customData": {
        "pageDescription": "Our product range"
    },
    "children": [
        {
            "id": "4424cbd7-c6df-4d7b-b916-cfe641754fd5.",
            "label": "suitcase",
            "seoRoute": "/products/:item",
            "seoRouteRegex": "^[\\/]products\\/[^\\s\\/]+$",
            "contentReference": "/products/sales/cases.html",
            "visible": true,
            "customData": {
                "available": false
            },
            "children": null
        }
    ]
}
Table 1. Functional meaning of the individual attributes
Name Description

id

The unique id of the navigation element.

label

The name of the navigation element to be displayed on the website.

seoRoute

The URL to which this navigation element leads. Typically the URL that is later displayed in the URL field in the browser.

seoRouteRegex

The seoRoute might contain variables. In this case, a regex can be specified in order to be able to match the concrete variants to the corresponding navigation element.

contentReference

The URL to the content which the application must retrieve and present to the user. In a headless FirstSpirit project this could be for example a CaaS URL, through which the page information is provided.

visible

Specifies whether the navigation element should be displayed in the frontend in the navigation.

customData

Arbitrary key/value pairs, which allow individual requirements of the application to be met. The number of values is limited to a maximum of five. The values must be of type number, boolean or string. Objects and arrays are not allowed here.

children

A list of nested navigation elements that have the same attributes (id, label, etc.). This creates a tree structure.

For detailed technical documentation of the individual endpoints, please refer to the OpenAPI Specification.

3. Features

The following subchapters describe the features of the Navigation Service from a functional perspective. They also link to the corresponding endpoints in the Swagger UI. Alternative representations can be found in the section OpenAPI Specification.

3.1. Language fallbacks

Navigations can be uniquely identified in the Navigation Service by their Id and language. Languages are always specified as an ISO code. If a requested navigation exists in a general language but not in the requested variant, it will be returned in the general language.

Example:
  1. Exists: (foo, en) Navigation with id foo in language en

  2. Requested: (foo, de_AT)

  3. Delivered: (foo, de)

It should be noted that the fallback behaviour only works in one direction. The Navigation Service can only fall back on more general navigations, not on more specific ones.

Example:
  1. Available: (foo, de_AT)

  2. Requested: (foo, de)

  3. Delivered: N/A

3.2. API endpoints

List all

It is possible to list all available navigations. The navigations are provided as a paginated list.
The OpenAPI specification for listing provides further information.

Edit entire navigations

The Navigation Service allows you to persist, query, update and delete navigations.
The OpenAPI specification for CRUD operations provides further information.

Edit subtrees

Instead of entire navigations, possible subtrees can also be queried. The navigation element is identified by its id. It is then returned with all its child elements. It is also possible to update subtrees of a navigation.
The OpenAPI specification for subtrees provides further information.

Breadcrumbs

A typical feature of a web application is a breadcrumbs view, which shows the path to the currently displayed element of the application. To facilitate this scenario, the Navigation Service offers the option of querying only the navigation elements between the root and the specified navigation element as a list.
The OpenAPI specification for breadcrumbs provides further information.

Querying subtrees by SEO route

A classic scenario is that a user opens a subpage of the web application directly using a URL. It is possible that only the navigation for the corresponding subtree is required for the display. For this purpose the Navigation Service offers the option to query subtrees not only by their id but also by their seoRoute attribute. In case a seoRoute contains variables, the navigation is identified by the seoRouteRegex.
The OpenAPI specification for SEO routes provides further information.

4. Authentication/Authorization

4.1. POST, PUT, DELETE

Due to the fact that the endpoints of the Navigation Service are freely accessible from the internet, all write operations must be explicitly secured. This ensures that the modification or deletion of navigations stored in the Navigation Service can only be done with the appropriate permissions. An internal identity and access management system hosted by e-Spirit is used for this purpose, at which in compliance with OAuth a valid access token must be retrieved and transmitted to the Navigation Service with every PUT, POST and DELETE request.

The authentication/authorization is automatically taken care of by the Navigation FirstSpirit module.

4.2. GET

In the default setting, read requests are not protected, so all information known to the Navigation Service is freely available on the Internet. Sensitive information must therefore not be part of the navigation of a web page.

On demand it is possible to change this, so that only the live navigations are freely available, while the preview navigations also require an authorization. Alternatively, it is also possible to make all data accessible only after authorization.

5. Navigation FirstSpirit module

FirstSpirit has an integration with the Navigation Service through the Navigation FirstSpirit module. If it is installed on the server and activated in the project, navigations maintained in FirstSpirit are automatically made available in the Navigation Service.

The Navigation Service is a product of e-Spirit AG, Dortmund, Germany.

Only the licence granted by e-Spirit AG is valid for the use of the product by the user.

7. Help

The Technical Support of the e-Spirit AG provides expert technical support covering any topic related to the FirstSpiritâ„¢ product. You can get and find more help concerning relevant topics in our community.

8. Disclaimer

This document is provided for information purposes only. e-Spirit may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. e-Spirit specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.