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 Crownpeak Technology GmbH 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,
    "permissions": null,
    "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,
            "permissions": {
                "allowed": ["customer", "admin"],
                "forbidden": ["anonym"]
            },
            "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.

permissions

Contains information about roles that are allowed to see this navigation element.

customData

Arbitrary key/value pairs, which allow individual requirements of the application to be met. The number of entries is limited to a maximum of five. The values must be of type number, boolean or string. The length of each key is limited to 200 characters. The length of each value is limited to 500 characters. 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 639 code (e.g., en). Countries are specified using ISO 3166-1 codes (e.g., US).

Only two-letter representation of both language and country codes are supported. Other representations of the codes with three-letters (ISO 639-2/3 and ISO 3166-1 alpha-3) or numerical (UN M49 codes) are not supported.

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: (de)

  2. Requested: de_AT)

  3. Delivered: (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: (de_AT)

  2. Requested: (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. Should the navigation contain multiple elements with the same id, the first found will be returned. 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 Crownpeak Technology GmbH 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.

4.3. Configuration

It is possible to configure the above default behaviour both for read and write operations. For example, you can completely disable authentication for write operations or make sure that some navigations require authentication even for read requests. See OpenAPI specification for further details.

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 Crownpeak Technology GmbH, Dortmund, Germany.

Only the licence granted by Crownpeak Technology GmbH is valid for the use of the product by the user.

7. Help

The Technical Support of the Crownpeak Technology GmbH 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. Crownpeak Technology GmbH 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. Crownpeak Technology GmbH 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.