...
A resource logically represents an entity whose operations have to be exposed using the RESTful service. It may optionally be used to specify just a path segment for a child URL with no methods defined on the resource itself.
Figure 6: Adding child resources and methods
- Add Method: Operations such as GET, POST, PUT, HEAD, DELETE and PATCH DELETE can be added by selecting the option Add Method as shown in the figure above.
- Add child Resource: A resource can be added to a resource element by clicking the option Add Child Resource.
...
Password
Password to be used by the RESTStub component while deploying the Web Service. If this password is not present in Realm.properties file the component will not launch.
JWT Authorization Configuration
Enable the Use JWT Authorization option and provide the credentials, Key ID, etc.
Figure 20: JWT Authorization Configuration properties
Use JWT Autherization
Enable JWT Authorization for all routes
- Username: Username to be used by the RESTStub component for verifying username in JWT token issue requests
- Password: Password to be used by the RESTStub component for verifying password in JWT token issue requests
- Key ID: The KID field as present in the public and private key pair set
Claims Confguration
The claims which will be present as key value pairs inside the JWT token
- Issuer: Refers to the servimauthority issuing the JWT token
- Audience: Refers to the audience intended for the JWT token
- Subject: Simple subject to be embedded in the JWT token
- Time to expire (in seconds): The time in seconds which would be taken for token expiry. Token issue time = time to expire = Token expiry time
- Additional Claims: Additional claims which can be customized for specific use cases as key-value pairs.
JWT API Route Configuration
The route configured in the Resource Configuraion panel which would be responsible for token authentication and token issue.
Key Pair Configuration
Private and Public Key Pair Set. Public and Private Key pairs in JWK format
...
Using Basic Authentication
| Anchor | ||||
|---|---|---|---|---|
|
Figure 21This panel helps to enable usage of API keys.
Figure 20: Additional Configuration to enable API Keys usage
Use API Keys
Enable this property to support API keys authorization
...
Validates the parameter URL. This property is in the enabled state by default.
File Directory
This option is applicable only when the method is set to "POST", the media type is set to "multipart/form-data" and the request content is of File type. When the request content is of file type, the file specified in the request will be uploaded to the directory mentioned in the File Directory field.
Append TimeStamp
Enable append timestamp option to append a timestamp to the filename that is uploaded to the file directory.
TimeStamp format
Specify the timestamp format that is to be appended with the filename.
Enabling Basic Authentication
...
- Stop the FPS Server if it is running.
- Open FPS profile in Fiorano Studio and navigate to FPS > Fiorano > Esb > Jetty.
- Select the Jetty mbean.
In the Properties of Jetty window, enable the BasicAuthSupported property and give the fully qualified path of Realm.properties file as the RealmProperties property.
Tip More information on Realms and Realm.properties file content are discussed in the next section.
- Save the profile.
Figure 2221: Enabling Basic Authentication in FPS Jetty server
...
| Anchor | ||||
|---|---|---|---|---|
|
Figure 2322: FES Connection Configuration properties
...
Execution Configuration
Figure 2423: Execution Configuration
Execution Timeout
...
Enable the checkbox under the Encrypt/Decrypt Configuration tab to encrypt the messages received/sent at/to the selected port.
Figure 2524: Execution Configuration
Please refer Encrypt Decrypt Configuration section in Common Configurations page.
Port Generation
Figure 2625: Sample Configuration
A request port and response port are generated for each method configured in the component with suffixes __Request and __Response respectively. The prefix of the port name will be the complete ID of the resource computed (as described in the "Resource" section) followed by the method name.
If a resource has multiple methods with the same name (two GET methods) then the method ID has to be specified for at least one of those methods. The method ID will be appended to the port name prefix to differentiate between these methods. For the sample configuration defined in Figure 23, the ports will be generated as shown in the Figure 24.
Figure 2726: Port Generation
Schema Generation
...
If there are any query parameters other than those specified in the configuration for the method, these parameters are added as part of the Parameters element.
For the sample configuration shown in Figure 23, the schema generated for port parent __POST_Request is as in Figure 25.
Figure 2827: Schema of port parent __POST_Request
...
For the sample configuration shown in Figure 23, the schema generated for port parent_child1_GET_Response is as in Figure 26.
Figure 2928: Schema of port parent_child1_GET_Response
...
| Note |
|---|
These scenarios involve the RESTConsumer microservice as well, which works in conjunction with RESTStub. Refer to the RESTConsumer documentation to configure and run the event processes. |
Configuring JWT Authentication in RESTStub
...
For JWT Authentication in RestStub, there needs to be one mandatory route for authenticating credentials and issuing JWT token.
...
| Note |
|---|
When the JWT option is enabled in the subsequent wizard panel, the other resources apart from the JWT Authentication resource will by default expect a JWT token in the header in the RFC6750 format “Bearer”. |
...
| Note |
|---|
Currently, RestStub only supports JSON input as credentials payload for JWT authentication. |
...
Key ID is to be entered as it is entered in the “Private and public key pair set” KID field.
| Warning |
|---|
This is mandatory to ensure ‘KIDs’ match. |
| Note | ||
|---|---|---|
Public and private keys are expected as key pair set in JWK format.
|
...
Useful Tips
- For SSL to work properly the JDK version used should be greater than 1.5.0_08 and the jars present in JDK_HOME/jre/lib/ext should be copied to $FIORANO_HOME/esb/lib/ext.
- When RESTStub component is configured to launch on HA (High Availability) Peer Servers
- If both Primary and Secondary Servers are on the same machine:
Initially, if RESTStub is launched on the Primary Server, the generated WADL URL contains Primary Server's jetty port number. In case of Primary Server failover, the Secondary Server becomes Active and relaunches the component. WADL will be regenerated and if the Secondary Server uses a different jetty port then the WADL URL is changed. The clients have to be reconfigured to use new URL in this case.
To avoid this situation, it is recommended to use the same jetty ports for both Primary and Secondary Peer Servers.
Jetty service will be started only after the server is started successfully. In case of HA, only one server will be active at a given time and the Jetty Server will be running only in the active server and there will be no bind exceptions even if both the servers use the same port number for Jetty.
- If both Primary and Secondary Servers are on the same machine:
...
- The service name must be unique for RESTStub instances configured on the same peer server.
- Headers received by the component are sent out as JMS properties with http_ prefixed to their name.
- The component acts as a helper to expose an event process as a RESTful service. The developer of an event process will have to take care that the functionality is exposed as per the guidelines of REST architecture.
- When the content type of request is application/octet-stream the content is sent as bytes content in the message, this will be present as bytes property. This can be retrieved as Base 64 encoded string in mapper using the funclet Byte-Content in JMS Message funclets.
| Tip |
|---|
Refer to the REST HelloWorld section to go through a simple example using the RESTStub service. Another example named REST Attachments illustrates advanced functionalities. |