API Gateway Pub   Share

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

Prefixes

It is generally a good practice, when using REST microservices, to configure the prefix of the APIs separately from the actual path used in each case, so that you'd generally have three parts to a URL: <host>/<prefix>/<service>. The prefix sometimes can designate the environment (say /sandbox/... or version /v1/... etc) or the specific server's routing to the services etc.

We use the following prefixes for the API Gateway:

• /diesel/rest - classic REST path mapping, also available as /api/rest
• /diesel/mock - classic REST preferring mocked rules, also available as /api/mock
• /diesel/react - direct message trigger

Note: if you have conflicts in the path with /api/rest mapping, then use the /diesel/rest prefix.

/diesel/react

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

• /diesel/react/diesel.ping
• /diesel/react/diesel.echo?payload=haha

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 "/dieselsample/echoJson")
=> (payload = {
  status : "echoJson",
  body : payload,
  verb : verb,
  headers : dieselHeaders
  })

This would be triggered when you use these URLs:

• /api/rest/dieselsample/echoJson?payload=haha
• /api/mock/dieselsample/echoJson?payload=haha

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

When you define these diesel.rest handlers, you can parse the path automatically into segments, using several ways - the most complex is using regular expressions:

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

Will match this call: /api/mock/myActualServer/create/John@ and it will 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 - this would be more typical:

• using : to identify a simple segment
• using * at the final segment to identify a path

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

$when diesel.rest(path ~= "/using/colonandstar/:user/*path")

Security and visibility

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

diesel.visibility=member

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. You can find this key after logging in, under your profile.

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>.+)")
...

OAUTH

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

When you run diesel locally, say in your own docker image, you can change the size of the various thread pools and that would provide a level of resource limitations. This is done in application.conf - here's an example:

diesel-dispatcher {
  type = Dispatcher
  executor = "thread-pool-executor"
  thread-pool-executor {
    fixed-pool-size = 5
  }
  throughput = 5
}

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

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 (
  group="elkpt", 
  regex="/diesel/rest/.*/elkpt/.*", 
  limit=10)

Reporting

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

{
 "global": {
  "maxServingApiRequests":8,
  "servedPages":0,
  "served":3510,
  "servedApiRequests":3490,
  "maxDieselThreads":"100",
  "serving":1,
  "limitedRequests":0,
  "maxServing":8,
  "maxDefaultThreads":"100",
  "servingApiRequests":0
 },
 "rateLimits": {
  "elkpt":  {
   "maxServed":3,
   "limited":0,
   "served":1529,
   "serving":0,
   "limit":80
  }
 }
}

You need to log in to post a comment!