REST Handler Flows

Requests from your defined REST routes can either be handled by custom flow or by a REST-aware shell (see next chapter). This chapter outlines the handling via a custom flow.

Topic Input

You'll need to create a flow that listens to messages at the topic you defined for your route. You find it after creating your route here:

Receiving JSON Data

If your route expects JSON data, you can extract the JSON values using the JSON Field Extractorcomponent, which will convert the JSON into Message properties, ready to be used by other flow components.

Route Parameters

Flow Director allows you to create a RESTful API, including route parameters and query strings.

You may define a route parameter using:param when defining your route.

For example, jobs/:id will store the param under id. A request to /jobs/2 will have the following in the body:

CODE

{
    "_params": {
        "id": 2
    }
}

URL query strings are also stored under _params in the request.

For example /jobs?status=open will contain the following body.

CODE

{
    "_params": {
        "status": "open"
    }
}

NOTE: Only route parameters are stored under _params in the body. If you send a JSON body, it is received as you sent it.

Sending a Response

Response Body (JSON)

Create a Text Message containing a JSON object with the HTTP response code and an optional message. The response code is optional. If it is not set, the response code will be 200 (ok) by default.

The response body is always a JSON object. It will be returned as a REST reply as is but without all fields starting with a _ like _http_status.

Response Body (Raw)

In some cases, a REST request should not return a JSON object but a custom format. In that case, return a JSON object but set a field _israw to true and put the custom formatted data into field raw as a string. You need to escape all JSON control characters.

Example:

CODE

{
    "_israw": true,
    "raw": "This is line 1\nThis is line 2 with \"quoted text\""
}

The REST response will then be:

CODE

This is line 1
This is line 2 with "quoted text"

Response Body (Redirect)

You can redirect REST requests by setting _http_status to 302 (redirect) and _location to the new address.

Example:

CODE

{
    "_http_status": 302,
    "_location": "https://www.example.com/nextstep"
}

Send

Connect the Text Message component to a Reply Output component to send it back as a reply.

Example:

CODE

{
    "_http_status": 404,
    "message": "Could not find a product with that id."
}

Resource not found HTTP response

Example:

The minimum components you need to handle an HTTP request:

Topic Input
Set Text Body
Reply Output

Any route that forwards to new_order will receive a 200 response with the message ok.

Components With New Messages

Certain flow components, such as the database Query component, result in new messages being created. This is usually the desired behavior; however, when responding to an HTTP request, it is required that the outgoing message must have the same ReplyTo and CorrelationId header values as the original message.

To ensure your outgoing message has the required headers, you would typically add 2 more components to your flow:

Store the original message in a Message Ref
Reference the original message in a Header Setter before the reply.

That sounds more complicated than it is; here is an example of a flow that copies the required header values.