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 |
---|---|---|
| false | If true, the REST module will be embedded into the application. |
| json | Sets the binding mode used by the REST consumer. |
| servlet | Sets the name of the Camel component to use as the REST consumer. Preferred and tested: servlet |
| true | Determines whether the endpoint shall be secured or not. The user authenticates against the partition.
|
| /custom | The shared context path of the REST resource. |
| ADMIN | Required role to be able to call the endpoint.
|
| false | Determines whether the endpoint shall be secured or not. The user authenticates against the partition.
|
| /api-doc | The context path of the documentation (relative to |
|
| Required role to be able to call the endpoint.
|
| true | Determines whether the data should be pretty-printed. |
| My API | Custom title of the API. This will appear in documentation. |
| 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 | |
---|---|---|---|
| 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): | |
| |||
|
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 | |
---|---|---|---|
| Up to IM 4.9.0 | IM 5.0.0 and above |
|
In camel-context.xml: | Create following route:
| Create following route:
| |
|
| ||
|
|
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