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
Create REST endpoint	Up to IM 4.9.0	IM 5.0.0 and above
Create REST endpoint	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):
Set properties
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
Create REST endpoint	Up to IM 4.9.0	IM 5.0.0 and above
Create REST endpoint	In camel-context.xml:	Create following route:	Create following route:
Set properties
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 Documentation

REST Module