API Gateway

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, get reports etc.

Entry points

There are several entry points for the API Gateway:

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

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 /api/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 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

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 (
  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
  }
 }
}

Was this useful?

By: Razie | 2021-01-09 .. 2024-11-16

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

You need to log in to post a comment!