Routing API requests through Elvis 6 using API plug-ins

Info: This feature requires Elvis 6.7 or higher.

Elvis API plug-ins extend the Elvis API with custom functionality, thereby enabling developers to create additional REST services for Elvis.

An external API can be developed in any programming language and needs to be accessible by the Elvis Server node(s). Elvis Server acts as a proxy server, handling all traffic between the process calling the API and the external API.

Example:  Assume we have a Web shop with products and we want to show product information in an Elvis Web client. In this case, you could create an Elvis web client plug-in that displays the products and it could fetch the information directly from your shop API. This might work, but has the following disadvantages: A cross-origin request is required as your shop API is hosted on a different domain. This can lead to security issues as cross-origin requests are often blocked. Authentication needs to be set up to ensure that your Elvis users can access the external API. We resolve both by running the API requests through Elvis. Cross-origin requests are now no longer required as the client only communicates with Elvis Server, not the Shop API. As for authentication: the API plug-in contains support for Elvis Capabilities, allowing you to for example configure the plug-in in such a way that only users who are logged in to Elvis are given access to the external API.

Configuration

An API plug-in consists of a single configuration file named api.config.xml.

Content

Its content is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
  <info>
    <version>
      <pluginVersion>1.0</pluginVersion>
      <requiresAtLeast>6.7.0.0</requiresAtLeast>
    </version>
    <description>Shop API</description>
  </info>
  <api>
    <url>https://shop-api.mycompany.com/</url>
    <requiredRoles>
      <role>ROLE_USER</role>
    </requiredRoles>
  </api>
</plugin>

Parameters

The following parameters can be defined:

pluginVersion	The version of the plug-in.
requiresAtLeast	The minimum version of Elvis Server that is required.
description	A short description of the plug-in.
url	The URL of the API to connect to.
role	(Optional) The Elvis role(s) required to run the process: ROLE_SUPERUSER ROLE_USER ROLE_WEB_CLIENT ROLE_CUSTOM_SHOP_API

Installation

Step 1. Create a folder containing the api.config.xml file and place it in the following location:

Elvis Server path > Config > plugins > active

Step 2. Install it by following the steps described in Installing and managing plug-ins in Elvis 6.

Sample

A sample plug-in is available on GitHub.