API Gateway Pub

Diesel has API Gateway capabilities: you can quickly define routes and coreograph microservices and expose them as higher-level microservices, control traffic, get reports etc.

Entry points

There are several entry points for the API Gateway:

  • /diesel/rest - classic REST path mapping
  • /diesel/mock - classic REST preferring mocks
  • /diesel/react - direct message trigger


The entry points of the form /diesel/react/<message> are wired directly to respective messages, for instance:

The arguments are passed as query parameters. Any rules matching the message and arguments are executed and the final result returned.

/diesel/rest and and /diesel/mock

This is a more classic path mapping for REST.

An example rule (the message name for these is always diesel.rest):

$when diesel.rest (path ~path "/diesel/echoJson")
=> (payload = {
  status : "echoJson",
  body : payload,
  verb : verb,
  headers : dieselHeaders

When using the mock entry point, the mocks are preferred (so $mock instead of $when).

You can parse the path automatically into segments, using several ways:

$when diesel.rest(path ~= "/myActualServer/create/(?<user>.+)")
=> myMailServer.create (user)

Will match this call: /diesel/mock/myActualServer/create/John@ and also parse and populate the user variable in context, from the respective path segment.

Other ways to match the same would be named segment variables:

$when diesel.rest(path ~= "/using/colon/:user/showme")

Security and visibility

The default visibility is set in the Reactor Configuration, using the property diesel.visibility. It can take the values member or public by default being public:


When set to memeber it only allows API calls to authenticated users, so one of a few authentication mechanisms must be used (HTTP Basic or cookie or X-Api-Key):

  • HTTP Basic will send the username/password as encoded BASE64 string, see https://en.wikipedia.org/wiki/Basic_access_authentication
  • cookie works when you login via the browser and then in the same session make a diesel API call to the same server - the browser cookie will authenticate you as a member
  • X-Api-Key is another supported mechanism. Each user has a random secret key assigned and when this is passed in via a HTTP header called X-Api-Key the respective user is authenticated

When using say member you can mark specific messages as public and it will allow them to be accessed without authentication, such as:

$msg <public> some.message(a,b,c)

$when <public> diesel.rest(path ~= "/myActualServer/create/(?<user>.+)")


You can use OAUTH and integrate to an OAUTH server, see Using OAUTH++

Rate limiting

Rate limiting for the API calls can be done in several ways.

Global limiting

In application.conf you can change the size of the various thread pools and that would provide a level of resource limitations.

Also there, in the diesel group, there are global static HTTP rate limits that you can enable:

diesel {
  staticRateLimiting = true
  staticRateLimitAll = false
  staticRateLimit = 80

These mean:

  • staticRateLimiting - this is a big on/off switch for rate limiting. If false, no rate limiting takes place. If ON, the global and group rate limiting configuration applies
  • staticRateLimitAll - rate limiting all calls, not just API calls
  • staticRateLimit - the global rate limit, across all groups and global calls

rate limiting groups

You can define a rate limiting group say group1 and then configure rate limiting for this group, based on path or header (for REST API flows), with these messages:

  • diesel.apigw.limit.path
  • diesel.apigw.limit.header

For instance:

$send diesel.apigw.limit.path (


Current status is reported in the /admin/status call, here's an example with only the relevant metrics:

 "global": {
 "rateLimits": {
  "elkpt":  {

Was this useful?    

By: Razie | 2021-01-09 .. 2022-10-07

Viewed 306 times ( | History | Print ) this page.

You need to log in to post a comment!

© Copyright DieselApps, 2012-2024, all rights reserved.