The Mache REST Service

Table of Contents Introduction Simplest usecase Further usecases Embedded Service Configuration Time to live Running as a service Endpoint Documentation/Testing

Introduction

The Mache REST Service is a configurable RESTful service that provides access to maps over a REST interface.

Simplest usecase

The simplest way to use the REST endpoint is as a standalone service. A Groovy script is used to configure and start the service, example of which are provided in the mache-rest\src\test\groovy folder. The groovy script is responsible for configuring the server (port, address, access restrictions) and providing a delegate that is used to create an instance of Mache upon request from a REST client. To start a REST service:

1. Include the mache-rest project from jcenter, if using gradle this is as simple as

      repositories {
         jcenter()
      }
      dependencies {
         compile "com.excelian.mache:mache-rest:+"
      }
      

2. Add any further required dependencies for your configuration to the gradle file, for example mache-cassandra or mache-rabbit
3. Add a groovy start script to the project, examples are provided in the mache-rest\src\test\groovy folder
4. Run the groovy start script to launch the REST service!

Further usecases

Embedded Service

It is also possible to configure the REST service to start embedded within another application. In this case the start code is almost identical to the code used to start the Standalone Service:

    MacheRestService restService = new MacheRestService();
    restService.runAsync((context) -> {
        try {
            return new RestManagedMache(
                mache(String.class, String.class)
                    .cachedBy(guava())
                    .storedIn(mongodb()
                              .withSeeds(new ServerAddress("localhost", 27017))
                              .withDatabase(keySpace)
                              .withSchemaOptions(SchemaOptions.CREATE_AND_DROP_SCHEMA)
                              .build())
                    .withNoMessaging()
                    .macheUp(), 0);
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    });

Configuration

In both a standalone and embedded configuration the REST service requires a delegate to be provided that is responsible for the creation of new maps in response to client requests, the delegate is provided with a context indicating the name of the requested map. When the delegate used to create maps is called a RestManagedMache is the required return type which provides the framework with both the map and any further configuration associated to the map.

Time to live

If is often desirable to remove large maps from memory after a specific period (perhaps daily), to achieve this a REST managed map may be created with the configuration parameter timeToLiveMillis, this parameter indicates the time in milliseconds that a map should live before being evicted from the cache. If no eviction is required this can be set to 0.

Running as a service

There is a separate guide to install Mache Running as a service.

Endpoint Documentation/Testing

The endpoints available are documented on the root URL of the configured REST service, by default http://localhost:8080/ this documentation is generated by Swagger http://swagger.io/ and also allows for simple testing & exploration of the API from within the browser.