Microservices Pub

Creating REST microservices is one of the basic diesel features: each message has a default binding to REST and there's significant API Gateway functionality, let's take a look:

  • default REST binding for each message
  • custom URL handling

See also:

Default URL for each message

When you define a message, say

$msg my.api (id,transactiontype,authtype,account,exp,amt,systemcode)

A default HTTP mapping is created for this message, which allows you to invoke it via a GET with all the parameters as query parms.

This may be ok for testing and quickly prototyping simple functionality. If you instead want a specific HTTP body to use for this service (such as XML or TEXT etc), then you have to define a request and response template, see REST and HTTP templates.

Note that the parser currently is not very smart, so make sure the message definition lists all the attributes you want to parse. This will be enhanced tommorow (yeah, right).

diesel.rest - custom URL

Another option to map messages to a desired API (other than the default URL) is to use the diesel.rest message (see more details in restMock-story and restMock-spec) :

$when diesel.rest (path ~path "/v1/ems/:env/device/:deviceType/:deviceId")
=> ems.inventory.query(env, deviceId, deviceType)

You can also include the verb int he match (supported verbs are GET, POST, PUT, PATCH, DELETE):

$when diesel.rest (path ~path "/v1/ems/:env/device/:deviceType/:deviceId", verb == "GET")
=> ems.inventory.query(env, deviceId, deviceType)

$when diesel.rest (path ~path "/v1/ems/:env/device/:deviceType/:deviceId", verb == "PUT")
=> ems.inventory.put(env, deviceId, deviceType, payload)

A special pattern is using asAttrs to handle anything sent to a POST as JSON body:

$when diesel.rest (
  path ~path "/v1/ems/:env/events/submit", 
  verb == "POST")
=> (temp = diesel.msg.attrs + {env : env})
=> ems.events.submit (temp.asAttrs)

All the values sent as a JSON body will be flattened as diesel.rest attributes and are accessed via dieselmsg.attrs as a JSON object (this is a built-in function). We're adding the env parsed from the URL (... + {env:env}) and passing it to ems.events.submit with asAttrs - which will expand the first level into a list.

A typed payload is also included - the following types are recognized: JSON, Array - everything else is String.

Invoking messages as microservices


The /diesel/rest prefix allows calling any diesel-based microservice.

/diesel/react and /diesel/wreact

The /diesel/react prefix is used to call a message directly as a REST service.

The /diesel/wreact prefix is similar to /diesel/react when the message is defined in a sub-section of a topic.

Visibility of messages

You can control the visibility and access to your new APIs in a few ways.

public messages

A public message will be accessible to members of this and trusted realms/projects.

You can make either all messages public by default with


or individually (the recommended approach):

$msg <public> my.api (id,transactiontype,authtype,account,exp,amt,systemcode)


Members of your realm/project, when logged in, will be allowed to call any message.

Trusted projects

A project can trust users coming from other projects as well, with this setting:


These users can then invoke any public message.


If you set an api key for the project, with:


TODO I should really call these proteted... not public...

Was this useful?    

By: Razie | 2021-01-09 .. 2021-02-08

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

You need to log in to post a comment!

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