REST Module

This module handles definition of custom REST endpoints via the Camel REST component.

Description

The module allows you to write endpoints directly without having to care about authentication. When the module is enabled and REST endpoints are present, the endpoints are present on a defined context path of IM. The implementation is backed by a servlet which is injected in IM’s (Spring Boot) own servlet, thus sharing the hostname and port with IM.

You cannot use the root or an arbitrary context path – they are reserved. Reserved endpoints are listed in the property integration.reserved.endpoints and setting the context path to one of those values will result in a startup failure.

Security

Pricefx is used as an authentication provider for all endpoints. You need to provide username/password and partition to log in properly. The partition part is optional – if you do not fill the partition, the default one from the Pricefx connection (if present) will be used.

Example of logging into a specific partition:

Username: mvich/integration Password: iAmTheBest PricefxConnection: partition=test, url=qa.pricefx.eu/pricefx --> will perform login into partition mvich under user integration with password iAmTheBest using url from default pricefx connection (qa.pricefx.eu/pricefx).

Example of logging into the base partition:

Username: integration Password: iAmTheBest PricefxConnection: partition=test, url=qa.pricefx.eu/pricefx --> will perform login into default partition test under user integration with password iAmTheBest using url from default pricefx connection (qa.pricefx.eu/pricefx)

The Pricefx connection is not mandatory for this module, but at least URL must be provided.

Properties

Property

Default Value

Description

Property

Default Value

Description

integration.rest.enabled

false

If true, the REST module will be embedded into the application.

integration.rest.binding-mode

json

Sets the binding mode used by the REST consumer.

integration.rest.component

servlet

Sets the name of the Camel component to use as the REST consumer. Preferred and tested: servlet

integration.rest.endpoints.secured

true

Determines whether the endpoint shall be secured or not. The user authenticates against the partition.

  • If false, unauthenticated users are permitted.

  • If true, the user must be at least authenticated.

integration.rest.endpoints.path

/custom

The shared context path of the REST resource.

integration.rest.endpoints.roles

ADMIN

Required role to be able to call the endpoint.

  • If empty, the user must be authenticated against the partition, but does not have to have any role.

  • If roles is set, the user must have at least one of the defined roles to access the endpoint.

integration.rest.doc.secured

false

Determines whether the endpoint shall be secured or not. The user authenticates against the partition.

  • If false, unauthenticated users are permitted.

  • If true, the user must be at least authenticated.

integration.rest.doc.path

/api-doc

The context path of the documentation (relative to integration.rest.endpoints.path).

integration.rest.doc.roles

 

Required role to be able to call the endpoint.

  • If empty, the user must be authenticated against the partition, but does not have to have any role.

  • If roles is set, the user must have at least one of the defined roles to access the endpoint.

integration.rest.pretty-print

true

Determines whether the data should be pretty-printed.

integration.rest.api-title

My API

Custom title of the API. This will appear in documentation.

integration.rest.api-version

1.0

Custom version of the API. This will appear in documentation.

Examples

Endpoint Protected, Doc Permitted

Create an endpoint which is protected by the role ADMIN and documentation is permitted to all.

Step

Manual instance

Provisioned instance

Step

Manual instance

Provisioned instance

  1. Create REST endpoint

Up to IM 4.9.0

IM 5.0.0 and above

 

In camel-context.xml:

<rest path="/v1/rebate" consumes="application/json" produces="application/json"> <description lang="US">Creating a program form (rebate agreement) in the Price Fx</description> <!-- health check service --> <!-- curl -X GET -H "Content-Type:application/json" -H "Authorization:Basic aXJvbm10bi1kZXYvaW50ZWdyYXRpb246RFlrbmliNTk4dmIzUXV4cA==" http://localhost:42080/api/delphi/v1/rebate/ping --> <get uri="/ping"> <description>Returns only OK message. Use for validating a login and the service availability.</description> <route id="apiPing"> <setBody> <groovy> def m = [ message:"OK" ] return m </groovy> </setBody> </route> </get> </rest>

Declare route:

Declare route:

But this is not enough for api-doc to be generated. You need to declare the following (similarly to how it was in IM version 4.x, but probably not possible in provisioned IM):

  1. Set properties

  1. Test

Endpoint Protected, Doc Protected

Create an endpoint which is protected by a role which the user does not have and the documentation is protected by a role which the user has.

Step

Manual instance

Provisioned instance

Step

Manual instance

Provisioned instance

  1. Create REST endpoint

Up to IM 4.9.0

IM 5.0.0 and above

 

In camel-context.xml:

Create following route:

 

Create following route:

 

  1. Set properties

 

  1. Test

 

Troubleshooting

Q: When the app is starting, I get the following error: “Multiple RestConsumerFactory found on classpath. Configure explicit which component to use.”

A: You probably have <rest> endpoints in context, but integration.rest.enabled is set to false. Set the property value to true.

IntegrationManager version 5.8.0