Upgrade to RESTHeart v4

Introduction

This page highlights the main differences between RESTHeart Platform v4 and RESTHeart v3 and provides guidelines for upgrading.

The RESTHeart team has worked hard to improve RESTHeart while keeping upgrading as simple as possible. The upgrade process has been tested successfully in complex installations.

The RESTHeart team supports you. Check our Services for free and professional support options.

Architecture

The new architecture explained

RESTHeart v3 has been growing over the last 5 years featuring a REST API for MongoDB and a strong security layer. The code got complex to update and maintain, so that RESTHeart Platform v4 is now split in modules clued together in a micro-service architecture.

This resulted in two projects that do one thing and do it well. Each of them can also be reused alone in different architectures.

The two micro-services are:

• restheart-core handles the REST API;
• restheart-security is responsible of enforcing the security policy acting as a reverse proxy for restheart-core.

It is very easy to start the two micro-services. Either using docker-compose or just starting them with java from the command line. In the latter case it is as easy as starting the two processes without specifying any configuration file. The default configuration seamlessly connects the two and just makes them work.

New features

RESTHeart Platform v4 introduces two main new features:

• Change Streams to handle real-time data streams via WebSocket connections.
• Transactions to handle multi-document transactions.

Default configuration

RESTHeart Platform 4 has some different default values.

The default configuration applies starting restheart-platform-core either without specifying a configuration file or specifying the parametric configuration file restheart.yml with the properties file default.properties

You can start RESTHeart Platform v4 with v3 backward compatible settings using the properties file bwcv3.properties

The following tables summarize the different default configuration values.

core

security

Representation Format

Following several community feedbacks, RESTHeart Platform v4 introduces a new default representation format that is more compact, easy to use and effective.

Read more at Representation Format

Examples follows:

RESTHeart v3

# read metadata and documents of collection restheart.coll -> GET /restheart/coll

{ "_embedded": [
    { <doc_1> },
    { <doc_2> },
    ...,
    { <doc_n> }
],
    "aggrs": [...]
    "checkers": [...],
    "transformers": [...],
    "streams": [...]
}

# count documents of collection restheart.coll -> GET /restheart/coll/?count&np

{ "_embedded": [], "_size": n }

RESTHeart Platform v4

# read documents of collection restheart.coll -> GET /coll

[
    { <doc_1> },
    { <doc_2> },
    ...,
    { <doc_n> }
]

# read metadata of collection restheart.coll -> GET /coll/_meta

{
    "aggrs": [...]
    "checkers": [...],
    "transformers": [...],
    "streams": [...]
}

# count documents of collection restheart.coll -> GET /coll/_size

{ "_size": n }

Plugins Development

The new Java API to extend RESTHeart has been improved in such a way that it is straightforward to adapt legacy implementations.

Core Plugins

Transformers, Hooks, Checkers and Services (aka Logic Handlers) are implemented extending interfaces that are identical to the legacy ones, with the exceptions that they were moved to the more meaningful package org.restheart.plugins.

The configuration of custom plugins has been simplified. Rather that declaring the implementation classes in the configuration file, plugins are registered using the @RegisterPlugin annotation. Plugins can optionally have a options set in the configuration file. An example follows.

Ping service implementation

@RegisterPlugin(name = "pingService",
        description = "Ping service")
public class PingService extends Service {

    private final String msg;

    /**
     *
     * @param confArgs arguments optionally specified in the configuration file
     */
    public PingService(Map<String, Object> confArgs) {
        super(confArgs);

        this.msg =  confArgs != null  && confArgs.containsKey("msg")
                ? (String) confArgs.get("msg")
                : "ping";
    }

    @Override
    public String defaultUri() {
        return "/ping";
    }

    /**
     *
     * @param exchange
     * @param context
     * @throws Exception
     */
    @Override
    public void handleRequest(HttpServerExchange exchange, RequestContext context) throws Exception {
        if (context.isOptions()) {
            handleOptions(exchange, context);
        } else if (context.isGet()) {
            context.setResponseContent(new BsonDocument("msg",
                    new BsonString(msg)));
            context.setResponseStatusCode(HttpStatus.SC_OK);
        } else {
            context.setResponseStatusCode(HttpStatus.SC_NOT_IMPLEMENTED);
        }

        next(exchange, context);
    }
}

Ping service optional configuration

pingService:
    #uri: "/hello"
    msg: Hello World!

Security Plugins

Security can be extended much easier compared to v3 and more types of security plugins are available: Authentication Mechanisms, Authenticators, Authorizers, Token Managers, Services, Initializers and Interceptors.

it is so easy implementing the security layer with restheart-security and it is so complete that we expect it to be used by other projects Andrea Di Cesare

The main reason behind the RESTHeart Platform being split in two micro-services versus the monolithic architecture of RESTHeart 3 was simplifying and hardening the implementation of the security layer.

Refer to Develop Security Plugins for more information.

HAL browser removed

The HAL browser has been removed, since the project is no longer maintained.

RESTHeart Platform v5 will include an Admin Web application that will replace it.

An online alternative that we suggest is http://restninja.io