This is the latest release in the 6.x.x family. For EI 7.0.0, click here.

All docs This doc
||
Skip to end of metadata
Go to start of metadata

The HTTP endpoint allows you to define REST endpoints using URI templates similar to the REST API. The URI templates allow a RESTful URI to contain variables that can be populated during mediation runtime using property values whose names have the "uri.var." prefix. An HTTP endpoint can also define the particular HTTP method to use in the RESTful invocation.



XML Configuration

The syntax is as follows.

<http uri-template="URI Template" method="GET|POST|PATCH|PUT|DELETE|OPTIONS|HEAD" />

HTTP Endpoint Attributes

Attribute

Description

uri-template

The URI template that constructs the RESTful endpoint URL at runtime.

Using the URI postfix property:

Let's take a look at it using an example. If you add a / between {uri.var.context2}{uri.var.postfix}, it is evaluated as an invalid invocation because {uri.var.postfix} contains a / at the start.

Example:

<http uri-template="http://{uri.var.host}:{uri.var.port}/{uri.var.context1}/services/{uri.var.context2}{uri.var.postfix}" method="get">

method

The HTTP method to use during the invocation.


Parameters

The parameters to configure an HTTP endpoint are as follows.

Parameter NameDescription
NameThis parameter is used to enter a unique name for the endpoint.
URI Template

The URI template of the endpoint. Insert uri.var. before each variable. Click Test to test the URI.

If the endpoint URL is an encoded URL, then you need to add legacy-encoding: when defining the uri-template.

e.g., uri-template="legacy-encoding:{uri.var.APIurl}"

HTTP Method

The HTTP method to use during the invocation of the endpoint. Supported methods are as follows.

  • Get
  • Post
  • Patch
  • Put
  • Delete
  • Options
  • Head
  • Leave-as-is
Show Advanced OptionsClick this link if you want to add advanced options to the endpoint. See Advanced Options for details of common advanced options you can add.

You can create HTTP endpoints by specifying values for the parameters given above.

Alternatively, you can specify one parameter as the HTTP endpoint by using multiple other parameters, and then pass that to define the HTTP endpoint as follows:

<property name="uri.var.httpendpointurl" expression="fn:concat($ctx:prefixuri, $ctx:host, $ctx:port, $ctx:urlparam1, $ctx:urlparam2)" />
<send>
<endpoint>
<http uri-template="
{uri.var.httpendpointurl}
"/>
</endpoint>
</send>

Examples

Example 1 - populating an HTTP endpoint during mediation

<endpoint xmlns="http://ws.apache.org/ns/synapse" name="HTTPEndpoint">
    <http uri-template="http://localhost:8080/{uri.var.servicepath}/restapi/{uri.var.servicename}/menu?category={uri.var.category}&amp;type={uri.var.pizzaType}" method="GET">
</http>
</endpoint>

The URI template variables in this example HTTP endpoint can be populated during mediation as follows:

<inSequence>           
            <property name="uri.var.servicepath" value="PizzaShopServlet"/>
            <property name="uri.var.servicename" value="PizzaWS"/>
            <property name="uri.var.category" value="pizza"/>
            <property name="uri.var.pizzaType" value="pan"/>
            <send>
                <endpoint key="HTTPEndpoint"/>
            </send>
</inSequence>

This configuration will cause the RESTful URL to evaluate to:

http://localhost:8080/PizzaShopServlet/restapi/PizzaWS/menu?category=pizza&type=pan

Example 2 - Sending a Message from a WebSocket Client to an HTTP Endpoint

The following sections walk you through a sample scenario that demonstrates how to send a message from a WebSocket client to an HTTP endpoint via the ESB Profile of WSO2 Enterprise Integrator (WSO2 EI):

Introduction

If you need to send a message from a WebSocket client to an HTTP endpoint via the ESB Profile of WSO2 EI, you need to establish a persistent WebSocket connection from the WebSocket client to the ESB Profile of WSO2 EI.
To demonstrate this scenario, you need to create two dispatching sequences. One for the client to back-end mediation, and another for the back-end to client mediation. Finally you need to configure the WebSocket inbound endpoint of the ESB Profile of WSO2 EI to use the created sequences and listen on port 9091.

Prerequisites
Configuring the sample scenario
  • Create the sequence for client to back-end mediation as follows:

    <sequence name="dispatchSeq" xmlns="http://ws.apache.org/ns/synapse">
      <switch source="get-property('websocket.source.handshake.present')">
        <case regex="true">
          <drop/>
        </case>
        <default>
          <call>
            <endpoint>
             <address uri="http://www.mocky.io/v2/56f84ee5240000d1127866c8"/>
            </endpoint>
          </call>
         <respond/>
         </default>
       </switch>
    </sequence>

    This sequence calls an HTTP endpoint.

  • Create the sequence for back-end to client mediation as follows:

    <sequence name="outDispatchSeq" xmlns="http://ws.apache.org/ns/synapse">
      <log/>
      <respond/>
    </sequence>
  • Configure the WebSocket inbound endpoint in the ESB Profile of WSO2 EI as follows to use the created sequences and listen on port 9091:

    <inboundEndpoint name="test" onError="falut" protocol="ws"
       	sequence="dispatchSeq" suspend="false" xmlns="http://ws.apache.org/ns/synapse">
       	<parameters>
           	<parameter name="inbound.ws.port">9091</parameter>
           	<parameter name="ws.outflow.dispatch.sequence">outDispatchSeq</parameter>
           	<parameter name="ws.client.side.broadcast.level">0</parameter>
           	<parameter name="ws.outflow.dispatch.fault.sequence">fault</parameter>
       	</parameters>
    </inboundEndpoint>
Executing the sample scenario
  • Execute the following command to start the WebSocket client:

    java -DclientPort=9091 -cp netty-example-4.0.30.Final.jar:lib/*:. io.netty.example.http.websocketx.client.WebSocketClient
Analyzing the output

If you analyze the log, you will see that a connection from the WebSocket client to the ESB Profile of WSO2 EI is established. You will also see that the sequences are executed by the WebSocket inbound endpoint.

OAuth Properties 

This feature allows users to configure the following OAuth grant types for HTTP endpoints. You can use either Authorization Code grant type (Refresh token grant type), Client Credentials grant type or Password grant type depending on your preferred third-party service.

You can use expressions (xpath or json path) to set these properties for. Refer Define Dynamic Expressions below for more details.
If you need to send additional parameters in the OAuth request body you can define them as a list of parameters. Refer Send additional parameters in OAuth request body.

  1. To use the Authorization Code grant type (Refresh token grant type) or the Client Credentials grant type you need to have WUM update level 1618940493641 or U2 EI 6.6.0.23.
  2. To use the Password grant type you need to have WUM update level 1631543692764 or U2 EI 6.6.0.56.
Authorization Code and Refresh token grant type

The authorizationCode element contains the following parameters that are used to configure OAuth for the endpoint. All of the following attributes are required.

Property NameDescription
clientIdThe Client ID provided by the service when you register your application.
clientSecretThe Client Secret provided by the service when you register your application.
refreshTokenThe Refresh Token obtained from the service while using the Authorization Grant.
tokenUrlThe token endpoint URL given by the service to obtain the access tokens.

An example is shown below.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <authorizationCode>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>9zLrZAYR5b</clientSecret>
                    <refreshToken>y2Ne4Fccrj</refreshToken>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
                </authorizationCode>
            </oauth>
        </authentication>
    </http>
</endpoint>
Client credentials grant type

The clientCredentials element contains the following parameters that are used to configure OAuth for the endpoint. All of the following attributes are required.

Property NameDescription
clientIdThe Client ID provided by the service when you register your application.
clientSecretThe Client Secret provided by the service when you register your application.
tokenUrlThe token endpoint URL given by the service to obtain the access tokens.

An example is shown below.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <clientCredentials>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>9zLrZAYR5b</clientSecret>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
                </clientCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>
Password grant type

The passwordCredentials element contains the following parameters that are used to configure OAuth for the endpoint. All of the following attributes are required.

Property NameDescription
clientIdThe Client ID provided by the service when you register your application.
clientSecretThe Client Secret provided by the service when you register your application.
usernameUsername of the user.
passwordPassword of the user.
tokenUrlThe token endpoint URL given by the service to obtain the access tokens.
<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <passwordCredentials>
                    <clientId>clientId</clientId>
                    <clientSecret>clientSecret</clientSecret>
                    <username>internal-user</username>
                    <password>[email protected]</password>
                    <tokenUrl>oauthServerUrl</tokenUrl>
                </passwordCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>
Send additional parameters in the OAuth request body

By default the grant_type, client_id, and client_secret parameters are sent in the OAuth request body. To send additional parameters you can define them as a list of parameters under the requestParameters tag as shown in the example below.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <clientCredentials>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>9zLrZAYR5b</clientSecret>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
	        <requestParameters>
                     	<parameter name="scope">read_only</parameter>
                  	<parameter name="user_role">tester</parameter>
                     </requestParameters>	
                </clientCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>


Define dynamic expressions

You can use dynamic values for OAuth configurations such as XPATH, JSON expressions or vault-lookup to get data from a secure vault. Make sure you define the elements within curly brackets.

<endpoint name="FoodEP" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://localhost:9192/service/foodservice">
        <authentication>
            <oauth>
                <clientCredentials>
                    <clientId>K2RbnGP7VS</clientId>
                    <clientSecret>{hashicorp:vault-lookup('secret/hello', 'clientSecret')}</clientSecret>
                    <tokenUrl>http://localhost:8678/token</tokenUrl>
	        		<requestParameters>
                     	<parameter name="scope">{ctx:oauth_scope}</parameter>
                     </requestParameters>	
                </clientCredentials>
            </oauth>
        </authentication>
    </http>
</endpoint>




  • No labels