REST Route

Parameters for REST API Routes

Parameter nameDescriptionDefault
REST Server NameThe base address of the HTTP endpoint

n.b. please do not insert http:// or https:// here; use the Rest Schema parameter
127.0.0.1
REST Server PortThe port of the HTTP endpoint8080
REST SchemaSchema to allow to distinguish between a plain text or a secured connection.

Allowed values:

- http
- https
https
Authentication TypeHTTP Server authentication type.

Allowed values:

- Basic
- none
Basic
Authentication ParametersAuthentication specific parameters. For example for the Basic authentication this field should contain the credentials in the format 'user:password'empty
REST ActionThe HTTP verb for the REST call

Allowed values:

- GET
- POST
POST
REST Header Property (1)Header property name in the Camel message where Camel Rest component will find the composed URL representing the endpoint to invoke.
For most of the use cases the default configuration works good and should not to be changed
evaluatedRestEndPoint
REST Original Topic (1)he name of the topic where the message was originally sent to by the device. By default it is read from the originalTopic property of the Camel message.
For most of the use cases the default configuration works good and should not to be changed
$simple{in.header.originalTopic}
REST Message ConverterMessage converter to convert the incoming message before forwarding it to the REST endpoint

Allowed values:

- none: no message converter will be used so the message forwarded to the Rest endpoint will be the same received by the broker
- json: the incoming message will be converted to a Kura payload then to JSON (see 1)
json
REST Message Converter ConfigurationAdditional configuration that may be required by the message converter. The value of this parameter is converter-specific. The basic json converter does not require any additional configuration.empty
REST Url OptionAdditional options to append to the Rest call urlempty
REST Topic MatchingDescribes how to map the incoming messages topics to Rest resource (see 2).
The field expects a list of rows composed by comma separated key value pair.
The key is the regex to match the incoming topics.
The value is the corresponding Rest resource.
The destination resource can contain variables recognized by the routing service (currently only ACCOUNT variable is supported).
The default value maps all the incoming topics into the ${ACCOUNT} (account name) URL. In case of multiple rows, no empty line can be inserted in between any of the rows.
.*,${ACCOUNT}
REST SSL/TLS Truststore CertCA certificate used by the REST route to authenticate the REST Server when establishing the HTTPS connection. See note (2) below.

Format: Base64 X509 UTF-8 encoded certificate
empty
REST SSL/TLS Keystore CertPublic key certificate used to identify the REST route to the REST Server when establishing the HTTPS connection (without private key). See note (2) below.

Format: Base64 X509 UTF-8 encoded certificate
empty
REST SSL/TLS Keystore KeyREST route key pair (private and public keys). Required if Keystore Cert is configured. See note (2) below.

Format: Base64 key pair
Supported: PEMEncryptedKeyPair, PKCS8EncryptedPrivateKeyInfo and PEMKeyPair)
empty
REST SSL/TLS Keystore PasswordPassword to access the Keystore Key, if anyempty

(1) The parameter has been removed starting from release 5.8.1. If specified it will be ignored.

(2) In HTTPS connections, the REST route plays the role of the REST Client.

Topic matching example

This is a topic matching example.
Please note that the incoming message use the JMS syntax (so the topic levels are . sepated instead of / separated)

(?:[^.]*?/){2}topic1/topic1_1,rest_path_1
(?:[^.]*?/){2}topic2,rest_path_2
(?:[^.]*?/){2}topic3/topic3_1,rest_path_3

This configuration forwards the messages for all the account's clients to different destination topics depending on 3 semantic topics:

MQTT semantic topicHTTP Endpoint
topic1/topic1_1/rest_path_1
topic2/rest_path_2
topic3/topic3_1/rest_path_3

Output Json example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "scopeId": "AQ",
  "deviceId": "RyO9_XKGRsw",
  "clientId": "client-id-0",
  "receivedOn": 1543486113,
  "sentOn": 1543486113,
  "capturedOn": 1543486113,
  "position": {
    "longitude": 0.0,
    "latitude": 0.0,
    "precision": 50,
    "heading": 240,
    "speed": 110,
    "timestamp": 1543486113,
    "satellites": 2,
    "status": 0
  },
  "channel": {
    "semanticParts": [ "one", "two", "three" ]
  },
  "payload": {
    "metrics": {
      "metric_one": {
        "value": "string_value",
        "valueType": "string"
      },
      "metric_two": {
        "value": 123,
        "valueType": "integer"
      },
      "metric_three": {
        "value": true,
        "valueType": "boolean"
      }
    },
    "body": "VGhpcyBpcyBhIGJvZHkgY29udGVudA=="
  }
}

Route Troubleshooting

Reachability

  • Ensure that the REST Server endpoint is reachable from Everyware Cloud services
  • Ensure that the REST Server does not belong to an address black-listed by EC

Transport Layer Security

When using secure HTTP connections (HTTPS), the route configuration may need digital certificates to be defined.

  • Check the requirements of the HTTPS connection to the REST Server to understand which certificates are involved.

The following are two common scenarios:

  • HTTPS with server side authentication only
    • Ensure the REST SSL/TLS Truststore Cert parameter has been set
    • Ensure the certificate above validates the server certificate
  • HTTPS with mutual authentication
    • Server side
      • Ensure the REST SSL/TLS Truststore Cert parameter has been set
      • Ensure the certificate above validates the server certificate
    • Client Side
      • Ensure the REST SSL/TLS Keystore Cert, REST SSL/TLS Keystore Key parameters have been set
      • Ensure the SSL/TLS Keystore Password parameter have been set if required by the REST SSL/TLS Keystore Key
      • Ensure the REST Server has the CA certificate to validate the REST route certificate (i.e. the certificate set in the field REST SSL/TLS Keystore Cert)
      • Ensure the CA certificate above validates the REST route certificate

Authentication

  • Ensure that the parameter Authentication Type is set according to the requirements of the Destination Endpoint
    • Authentication type Basic will try to establish an HTTP request with Basic Auth (credentials are required).
    • Authentication type none will try to establish an HTTP request with no authentication.