Usage

Ekko Proxy has an easy and intuitive web client made by engineers for engineers.

Create a Ekko Proxy instance

To create a proxy click the Create Proxy navigation link. You should now see the Create Ekko Proxy page below where you can enter the proxy details to setup a new HTTP or JDBC based Ekko Proxy instance.

ekkoproxy settings screen

The fields on the HTTP Proxy Settings page are described below:

Field Description
Import/Export settings Click to select import / export option from menu:

: Import Settings...
Shows import settings dialog where Ekko Proxy settings files (EkkoProxySettings_*.json or a zip file containing one or more of the same) can be dragged & dropped or selected for import.

: Export Settings
Exports any Ekko Proxy settings files (EkkoProxySettings_*.json) to your browser downloads directory as a zip file.

: Install License...
Shows install license dialog where the Ekko Proxy license (ekkoproxyserver.lic) and certificate (ekkoproxyserver.der) files can be dragged & dropped or selected for installation.
Listener Https Select to toggle the listener port between:

: HTTP
: HTTPS
Listening Port * The port number [1 - 65535] that the Ekko Proxy should be listening on for incoming messages. Clients connect to this port on the host where Ekko Proxy server is hosted be it on a localhost computer or on a remote server.

Note when the field gains focus a suggestions list of previously defined proxies will show, if any exist.

Note when the field looses focus or when picking from the suggestions list, then previously saved settings will be automatically loaded, if any exist. Alternatively pressing enter will also load any saved settings and move focus to the 'CREATE PROXY' button where pressing enter again will create the Ekko Proxy instance.
Lastly its also possible to drag & drop an existing proxy settings file (e.g. EkkoProxySettings_1080.json) on to this screen to fill in the fields.
Target Host * The host / ip of the target server where the requests will forwarded to in passthrough or record mode.

Note this should be the target host name or ip address without the protocol part i.e. without 'http://' or 'https://' as this is controlled by the 'Target Https' setting below.
Target Port * The port number [1 - 65535] of the target server where the requests will forwarded to in passthrough or record mode.
Target Https Select to toggle connecting to the target using:

: HTTP
: HTTPS
Certificate File An SSL certificate can be specified if required for the target HTTPS connection.

: Upload Certificate
Shows upload SSL certificate dialog where a SSL certificate file can be drag & dropped or selected for upload.
Certificate Password An SSL certificate password can be specified if required for the target SSL certificate.
Output Directory * The directory to where the Ekko Proxy instance should store recordings. Can be a full path or relative.

Note this field may be read-only if a fixed output directory has been specified on the command line when starting the Ekko Proxy server.
Description An optional description of the proxy that will be displayed on the proxy view.
If not set it will default to 'The Ekko Proxy service virtualization server is started|stopped'
Output Format The output format to use when displaying requests and responses:
  • Auto: Determines the formatting (Json or Xml) from the Content-Type header.
  • Json: Always use Json formatting.
  • None: Use no formatting.
  • Xml: Always use Xml formatting.
Operation Mode The operation mode of the Ekko Proxy instance.
See Operation modes section for details.
Expression Format The expression format to use in the 'Organising Recordings' and 'Normalise Recordings' tables:
  • JsonPath: Use JsonPath expressions.
  • Regex: Use regular expressions.
  • XPath: Select to use XPath expressions when working with XML.
Send CORS headers Tick this box if you want the proxy to automatically respond to HTTP OPTIONS requests and send CORS headers in all responses.
Organising Recordings If you want to organise the recorded requests and responses into various sub-folders based on information in the requests, then you can specify XPath, JsonPath or Regular expressions here to select the information from the requests and use to create sub-folders under the output directory.

Note the order of the expressions determine the order of the sub-folders.

See Organising recordings for more details.

: Adds a new row to the table.
: Launches the Expressions test dialog.
: Use request URI in output path. If selected, the request url will be part of the output folder path where the requests and responses are saved to. For example if the 'Output Directory' is set to C:\temp and a request is having a path of /foo/bar then the requests and responses for this web service will be saved in C:\temp\foo\bar.
Normalise Recordings The filename key for a request and response pair is made up of hashed request information. There may be parts of the request that are unique per request e.g. a transaction id, session id or timestamp etc. which would prevent playback mode from working as the filename key would never be the same. To solve this you can specify XPath, JsonPath or Regular expressions here that will remove any matching fields in the request e.g. //ServiceRequest/SessionId before constructing the recorded filename key.

Note when using XPath or JsonPath expressions you can only exclude request information from the request body. If you need to exclude information from the URI, query string or headers (if 'Include HTTP headers in filename key' option is selected) then please use Regular expressions instead.

See Normalise recordings for more details.

: Adds a new row to the table.
: Launches the Expressions test dialog.
: Include HTTP headers in filename key. If selected, the HTTP request headers are included in the key for the saved requests and responses. Note if there are request headers that vary per request for a service then you should either not use this option or use regular expressions in the 'Normalise Recordings' table to exclude them as otherwise playback would not work.
: Save formatted content. If selected the saved recordings will be formatted according to the Output Format.
CREATE PROXY Clicking the button (or pressing enter when focused) will create the new Ekko Proxy instance, provided there are no validation errors.

Note you need a license to be able to create more than one proxy instance.

An example of a filled HTTP proxy settings screen can be found below:

ekkoproxy HTTP settings screen filled

Note you can also drag & drop an existing proxy settings file (e.g. EkkoProxySettings_1080.json) on to this screen to fill it in.

Note the number of concurrent Ekko Proxy instances that can be created is limited without a license.

Similarly a JDBC database proxy can be created by clicking on the JDBC Proxy tab as per below screenshot:

ekkoproxy JDBC settings screen filled

The fields (that differs from the HTTP proxy) on the JDBC Proxy Settings page are described below:

Field Description
Secure Sockets Toggles between Secure Sockets being on/off:

: Secure Sockets Off
: Secure Sockets On

Note this is only applicable for when using RMI to communicate with the EkkoProxy JDBC proxy instance.
Connection Type The connection type provides two options on how connections to the database are created:
  • DriverManager: creates connections to a database via the DriverManager class using a database URL. A driver implementation class will have to be specified in the 'Driver Classname' field to use this way.
  • DataSource: creates connections to a database via the DataSource class using given properties. A data source implementation class will have to be specified in the 'DataSource Classname' field to use this way.
Note the DriverManager does not provide connection pooling out of the box but if the "ekkoproxy.jdbc.connectionPooling" setting (see installation) has been set connections will be pooled using Apache commons dbcp2.
Driver Classname * If DriverManager is selected as the connection type then this field is displayed and needs to have the full classname of the JDBC database driver to be used for creating the connections e.g. 'oracle.jdbc.driver.OracleDriver'.
DataSource Classname * If DataSource is selected as the connection type then this field is displayed and needs to have the full classname of the JDBC database datasource to be used for creating the connections e.g. 'oracle.jdbc.pool.OracleConnectionPoolDataSource'.
Username The database username, if any.
Password The database password, if any.
URL * The URL of the database connect string e.g. jdbc:oracle:thin:@some.machine.test.group:1522/DB01.test.ekkoproxy.com

Note this field is shown only if a DriverManager connection type is selected.
Verbosity Level The verbosity level determines which JDBC commands triggers events to be fired and subsequently shown in Ekko Proxy:
  • All: show all commands.
  • Connections and Statements: shows commands for all connections and statements.
  • Connections: show commands for connections only.
  • Statements: show statement commands only.
  • PreparedStatements: show prepared statements commands only.
  • CallableStatements: show callable statements commands only.
Mock Path * Sets the mock path for this proxy that's used as a HTTP equivalent request URL. This can then be used to define matching mock responses in the mock editor.
Driver Properties Can be used to specify properties to be passed into the DriverManager.getConnection call or to be set on the Datasource instance.

Note when the properties are set on the Datasource instance they need to match the case of the class setter e.g. if 'setURL' then use 'URL' as the property name.
TEST CONNECTION Provides the option to test if a connection can be created to the database with the details currently provided.

The below screenshot shows an example of a filled JDBC proxy settings screen using a DriverManager:

ekkoproxy JDBC settings screen filled driver

Similarly the screenshot below shows an example of a filled JDBC proxy settings screen using a Datasource:

ekkoproxy JDBC settings screen filled datasource

Operation modes

Ekko Proxy has four different operation modes:

  • Passthrough - in this mode all requests and responses going through the proxy will be passed directly to the target server or database.
  • Record - this mode will save all requests and responses going through the proxy to the target server or database.
  • Playback - in the playback mode HTTP proxies will respond with a recorded or mocked response, if one exists, otherwise it will pass the request to the target server and respond with the server's response.
    For JDBC proxies the playback option works using a mocked connection so no database calls will reach the target database in this mode. If there are any recorded or mocked responses that match a request then these will be played back and if not you would get an empty result set, say for a executeQuery call. So to get proper responses you can either run in Passthrough or Record mode first to capture responses or setup mocks in the Mock Editor.
  • Playback or Record - in the playback or record mode Ekko Proxy will respond with a recorded/mocked response, if one exists, otherwise it will pass the request to the target server and record the response so that when the same request is seen again it will be played back from thereon.
    Note this mode is not supported for JDBC proxies.
  • Playback on Error - this mode will only playback a saved or mocked response (provided either exists) if a HTTP error status of 500 or above is received from the target server. If a recording or mock does not exist the original error response is sent.
    Note this mode is not supported for JDBC proxies.
The different operation modes for HTTP proxies are explained further in the below flow diagram:

Ekko Proxy operation modes

Organising recordings

The 'Organising Recordings' table along with the 'Use request URI in output path' field allows you to organise how the recordings are stored on disk under the 'Output Directory' path.

For example if you have set 'Output Directory' to C:\temp, selected the 'Use request URI in output path' option and you have the following SOAP request on the /SystemUtilitiesService URI:

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:EkkoProxy.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:EkkoProxy.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:EkkoProxy.Schema.Header">789012</ns2:UserId>
         </Header>
         <SystemFunctions>
            <ApplicationId>2</ApplicationId>
            <ApplicationType>3</ApplicationType>
            <SystemParameters>
               <SystemParameter>
                  <ParameterIdentifier>IsAvailable</ParameterIdentifier>
               </SystemParameter>
            </SystemParameters>
         </SystemFunctions>
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

And you wanted to store these and other requests of the SystemUtilitiesService under the method requested and the user id, as highlighted above, you could add the following XPaths to the 'Organising Recordings' table:

  1. local-name(//Envelope/Body/*[1])
  2. //UserId/text()

The order of the expressions determine the sub-folder order, which given all of the above would end up being:

C:
|_ temp
   |_ SystemUtilitiesService
      |_ GetSystemFunctionsRequest
         |_ 789012
               - 2c94b878a468ce4b3a9a2a3ea37df739_req.txt
               - 2c94b878a468ce4b3a9a2a3ea37df739_resp.txt

The *_req.txt and *_resp.txt files contain the recorded request and response respectively.

Likewise if you are working with JSON etc. you can use JsonPath or regular expressions instead pick out values e.g. $.userId or \"userId\":\s?\"(.*)\" (note the group brackets used to select the value part only) would fetch the value of the userId field given JSON like:

{
    "userId":"JohnDoe"
    .
    .
}

Note you can change the response content of a saved response file at any time to have the amended response played back on the next request for the resource.

The recorded requests can also be dragged & dropped on a Ekko Proxy (messages table part) to resend them provided the proxy is running in passthrough mode.

Likewise recordings can be organised for JDBC proxies. By default they are organised by the given mock path and the JDBC command's object and method. For example calling executeQuery on a PreparedStatement would create a folder structure as: C:\temp\sqlrequest\PreparedStatement\executeQuery provided the output directory was 'C:\temp' and the mock path was '/sqlrequest'.

To organise further you can specify one or more regular expressions. For example to organise by the database table name used in a query you could simply use: FROM ([a-zA-Z_]*) to extract the table name from the SQL query. This will then be appended to the output path e.g. C:\temp\sqlrequest\PreparedStatement\executeQuery\SomeTableName.

Normalise recordings

The 'Normalise Recordings' table allows for normalising recordings by removing any unwanted uniqueness thus enabling them to be played back.

For example given a SOAP request message like:

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:EkkoProxy.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:EkkoProxy.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:EkkoProxy.Schema.Header">789012</ns2:UserId>
            <ns3:TransactionId xmlns:ns3="urn:EkkoProxy.Schema.Header">3M4bSjb3jP4b2j3hL</ns3:TransactionId>
         </Header>
         <SystemFunctions>
            <ApplicationId>2</ApplicationId>
            .
            .
         </SystemFunctions>
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

In the example above the TransactionId is a unique identifier that differs per request, which if not excluded, would create a new recording every time and you would not be able to have it played back. So to overcome this scenario you can add expressions in the 'Normalise Recordings' table to exclude this, and any other data items like it, from the unique key used to identify a recording.

In this particular example adding //Header/TransactionId to the 'Normalise Recordings' table would be all that's needed to exclude the node from the recording key.

Note for XPath expressions you don't have to worry about namespaces.

Similarly JsonPath and regular expressions can be used to exclude unique information in the request body as well as the request URI, although the latter cannot be done using XPath or JsonPath expressions.

For example given a REST GET request below:

http://localhost:3094/microservice/v1/books?bookId=112233&timestamp=123456789

You can exclude the unique timestamp query string parameter by adding a simple regular expression &timestamp=\d* to the 'Normalise Recordings' table.

Likewise if you need to exclude one or more unique fields in for example a JSON request body like below:

{
    "glossary": {
        "title": "example glossary",
        "GlossDiv": {
            "title": "S",
            "GlossList": [
                {
                    "ID": "ISO 8879:1986",
                    "CreatedDate": "2018-10-05T14:48:10.000Z",
                },
                {
                    "ID": "ISO 1345:1988",
                    "CreatedDate": "2018-11-15T16:32:14.000Z",
                },
                .
                .
            ]
        }
    }
}

Using either a regular expression like \"CreatedDate\"\s?:\s?\".*\", or a JsonPath like $.glossary.GlossDiv.GlossList[*].CreatedDate would exclude the CreatedDate from being part of the recording key so that if the same message is sent again but with a different CreatedDate value it will still be played back.

Note as long as the value(s) that you don't want to include in the filename key are removed then it doesn't matter if the remaining message is valid JSON or XML as it's only used for the filename key generation.

Similarly you can use regular expressions for JDBC proxies to normalise the SQL query for recording purposes. For example if you had the query below:

SELECT
  GROUP_CODE,
  GROUP_CODE_DESCRIPTION,
  LOOKUP_ID,
  LOOKUP_TYPE,
  LOOKUP_VALUE,
FROM
  LOOKUPS
WHERE
  CHANNEL LIKE ?
  AND (
     GROUP_CODE = 'GRP_ID_FOO' OR
     GROUP_CODE = 'GRP_ID_BAR'
  )

And you would like to have the same response recording played back for any GROUP_CODE values then you could add a regular expresion like: GROUP_CODE = '[A-Z_]*' to remove the group code values from the resulting filename key.

Managing a Ekko Proxy instance

Once a Ekko Proxy instance has been created, a link to it will appear in the navigation bar from where it can be managed. Clicking that link will show the Ekko Proxy management screen as can be seen in the HTTP example below:

ekkoproxy HTTP management screen

HTTP messages going through the proxy will appear in the table as shown above.

Note the number of current messages displayed is limited without a license.

JDBC instances are very similar as shown in the example below:

ekkoproxy JDBC management screen

Fields and functions

The fields and functions of this part of the Proxy management view are as follows:

Field Description
HTTP/JDBC Proxy <port>
<proxy description>
The proxy type followed by the port is displayed top left with the proxy description immediately below.
Search The search field can be used to search the table showing the messages going through the Ekko Proxy instance. The search supports regular expressions. Pressing the Enter key or clicking the search button will initiate the search and filter the table showing only matches. The table header will show if it's filtered or not by displaying the filtered icon:
Link status A green link means the Ekko Proxy client is connected to the Ekko Proxy Server.
A red link means the Ekko Proxy client has been disconnected from the Ekko Proxy Server.
Proxy Information On hover, displays proxy settings information. For HTTP proxies the following is displayed: 'Output Directory', 'Listener Https', 'Target Https', 'Output Format', 'Expression Format' and 'Certificate File' if one was configured.
For JDBC proxies the information includes: 'Output Directory', 'Secure Sockets', 'Mock Path', 'User' and either the configured 'Driver' or 'DataSource'.
Target Host The host / ip of the target server where the requests will forwarded to in passthrough or record mode.
This can be edited only when the proxy is stopped.

Note setting is only applicable for HTTP proxies.
Target Port The port number [1 - 65535] of the target server where the requests will forwarded to in passthrough or record mode.
This can be edited only when the proxy is stopped.

Note setting is only applicable for HTTP proxies.
Verbosity Level The verbosity level determines which JDBC commands triggers events to be fired and subsequently shown in Ekko Proxy:
  • All: show all commands.
  • Connections and Statements: shows commands for all connections and statements.
  • Connections: show commands for connections only.
  • Statements: show statement commands only.
  • PreparedStatements: show prepared statements commands only.
  • CallableStatements: show callable statements commands only.
Note setting is only applicable for JDBC proxies.
Operation Mode The operation mode of the Ekko Proxy instance. See the Operation modes section for a description of what the different modes of operation are.
This can be edited only when the proxy is stopped.
Pause / Resume Pressing the 'Pause' button will stop new messages from being displayed in the table whilst paused.
Pressing 'Resume' will refresh the table and it will again update automatically when new messages appear.

Note 'Pause' and 'Resume' only affects the view of the current client i.e. other clients viewing messages for the proxy will continue to see updates.
Stop / Play Pressing the 'Stop' button will stop the running proxy and any requests sent to it will not be able to connect. Pressing 'Play' starts the proxy again. Whilst stopped the 'Target Host', 'Target Port' and 'Operation Mode' fields can be modified allowing a change of target destination or operation mode.
Recordings Drawer The 'Recordings Drawer' button opens the Recordings drawer showing any existing recordings found in the output directory of the proxy.
Delay The 'Delay' button opens the Delay Settings dialog allowing for response delays to be set.
Show Statistics Opens the statistics dialog showing request hits and HTTP method distribution.
Compare The 'Compare' button provides the option to compare two requests or responses in the Compare dialog.

Note this button is only enabled when exactly two messages are selected.
Open The 'Open' button opens a recorded request and/or response in a new browser tab / window. The request and/or response needs to have been recorded i.e. saved before it can be opened in a separate window.

Note depending on browser settings, especially if opening both the request and response in one go, then you may need to enable pop-ups for the Ekko Proxy client as otherwise the action may be blocked by the browser.
Mock Generates a mock from the selected request / response. You can amend etc. the generated mock in the Mock Editor as required after it's been generated.

Note you must stop & start the proxy(s) that you want to pick up the new generated mock.
Save The 'Save' button allows for saving / recording the requests and responses of the selected messages that are not already saved / recorded or played back i.e. messages that were passthrough messages.
Resend Resends the selected requests.
Clear Clears the selected messages from the table and in-memory Ekko Proxy server cache.
Delete Deletes the selected saved / recorded messages from disk.

Note this cannot be undone!

Messages table

The messages table displays the incoming requests/responses going through the proxy. Saved request recording files can also be dragged & dropped on this table to send these requests again (Note to reach the target server, the Ekko Proxy should not be in Playback mode).

The following describes the messages table columns:

Field Description
Time The timestamp of the message (HH:mm:ss.SSS dd-MM-yyyy).
Method The HTTP method of the message e.g. POST.

Note this is only applicable for HTTP proxies.
Status For HTTP proxies this is the HTTP status of the message e.g. 200 OK.

For JDBC proxies it will say 'Success' if there were no SQL error or 'Failed' followed by an error code if an SQL error occurred.
Mode The operation mode used to serve the message e.g. Playback.
Request Url For HTTP proxies this is the request URL of the HTTP message.

For JDBC proxies this is the 'request URL' or rather command path of the SQL request. It is comprised of the JDBC object name followed by the method called on it e.g. /PreparedStatement/executeQuery. For more information see JDBC mocking.
Filename The filename of the recording if the message was recorded or played back.
Duration The length of time it took to respond (mm:ss.SSS).
If a delay is set for the request then this time will include the delay time and a timer icon is displayed to indicate that it was a delayed response.

Note multiple messages can be selected by clicking the check box or by holding down the Ctrl key while clicking on a message row.

For HTTP proxies request recordings can be dragged & dropped on to the messages table to send them again as shown in the example below:

ekkoproxy messages table dnd

Recordings drawer

The Recordings drawer displays a list of any recordings found in the output directory of the proxy:

ekkoproxy recordings drawer

The Recordings drawer lists the request line and filename for each recording. If multiple recordings exist for a particular request then these are grouped together. Clicking on an recording will display the details of the request and response (provided one exists) in the Request Details section. Recordings can be filtered by entering a regular expression enabled search string. Lastly recordings can be either imported or exported by clicking the Import/Export button .

A context menu can be accessed by clicking the more button () providing the following menu options:

Menu Item Description
Delete Recording Deletes the selected saved / recorded messages from disk.

Note this cannot be undone!
Open Request Opens the request file in a new browser tab / window.
Open Response Opens the response file in a new browser tab / window.
Send Request Resends the selected request.

Note a license is required for showing all recordings in the drawer.

Request and response details

The second half of the Proxy management view shows the request and response details of a selected message as shown below.

The request details are editable allowing for a new request to be created or for amending an existing one. When creating a new request the details can either be entered manually, selected from the Recordings drawer or a saved request recording can be dragged & dropped in the Request Details area - the latter applies only to HTTP proxies.

Request Details

The top part of the HTTP request details section is shown below:

ekkoproxy management screen HTTP bottom header part

The fields and functions of this part of the Proxy management view are:

Field Description
Request Method The request HTTP method of the currently selected request, if any.
The field is editable allowing for it to be set or changed.
Request Url The request URI of the currently selected request, if any.
The field is editable allowing for it to be set or changed.
Send The 'Send' button will send / resend the current request content.
Response Status The HTTP response status for a request is shown directly below the Send button in the tab area.

For JDBC proxies this looks like:

ekkoproxy management screen JDBC bottom header part

The SQL details shows the JDBC 'Request URL' i.e. command path consisting of the object name and method. To the right there is a resend button that's enabled for requests that can be re-executed.

Request tab

For a HTTP proxy the request tab displays the message body of the HTTP request:

ekkoproxy management screen HTTP message request body

By default the data is displayed according to the output format setting. A speed dial menu at the bottom right of the area provides the following display options:

Field Description
Strip before send When on, the message (XML or JSON only) will have any formatting stripped off before the request is sent. Conversely when off, the message is sent as is displayed.
Formatting Turns the formatting and syntax highlighting on/off. If you edit the request, with a view to send an altered message, then the version you are editing (formatted or raw) is the only one altered and the message is sent as displayed.
The option is not available if the output format is set to None.
Word wrap Turns line word wrapping on/off.

Similarly for a JDBC proxy the request tab displays the SQL, if applicable, of the request:

ekkoproxy management screen JDBC message request body

Response tab

For a HTTP proxy the response tab displays the message body of the HTTP response.

ekkoproxy management screen HTTP message response body

By default the data is displayed according to the output format setting. A speed dial menu at the bottom right of the area provides the following display options:

Field Description
Formatting Turns the formatting and syntax highlighting on/off.
The option is not available if the output format is set to None.
Word wrap Turns line word wrapping on/off.

For a JDBC proxy the response tab displays the SQL response.

ekkoproxy management screen JDBC message response body

If the response is a result-set then it will be displayed in a tabular format. The table is searchable and the data can be downloaded as a CSV file. A speed dial menu at the bottom right of the area provides the following display options:

Field Description
Table view Swaps between displaying the data in tabular or json format.
Word wrap Turns line word wrapping on/off. This is only available if the response is not in tabular format.

Headers tab (HTTP)

The headers tab displays the HTTP message request and response headers.

ekkoproxy management screen HTTP headers

The request headers can be edited in either table or bulk () modes. In bulk view mode headers are displayed all together as shown below:

ekkoproxy management screen HTTP headers bulk view

Cookies tab (HTTP)

The cookies tab shows the request cookie and the response set-cookie HTTP headers in table form making them easier to view and edit (former only).

ekkoproxy management screen bottom part

The code button () toggles between displaying values Url encoded or decoded.

For details of the standard cookie properties listed in the response cookies table see Cookie Specification.

Note HTTP request recordings can be dragged & dropped on the Request Details area to fill it with the request details of the recording as seen below:

ekkoproxy messages table dnd

Parameters tab (JDBC)

The parameters tab displays the query parameters for the SQL command, if applicable.

ekkoproxy management screen JDBC parameters

The parameters can be edited and the SQL command sent again with the new parameter values.

Client Info tab (JDBC)

The client info tab displays information that can be set by a client when connecting.

ekkoproxy management screen JDBC parameters

By default the client's IP address (ep-jdbc-client.address) and host name (ep-jdbc-client.name) are always sent. More client information properties can be set via system properties by passing the system property names to lookup via a semicolon delimited string set in a property named ekkoproxy.jdbc.clientinfo.properties when connecting.

Creating a virtual API manually

Creating virtual services manually (as opposed to record & playback) can be achieved in a couple of ways as explained further in the following sections.

Using recordings

Creating a virtual HTTP response message can be done by firing the request in question through the proxy and then performing the save action to record the request. This generates the request recording file e.g. 34af1895bca9eef210ae5836e0ae65be_req.txt in the Output Directory as per organising recording rules. You can then simply create an equivalent response file e.g. 34af1895bca9eef210ae5836e0ae65be_resp.txt and put the desired response status and content in that file. The format of the response file should follow the HTTP Specification which very simply put is:

Status line
Response headers (if any)
CRLF
Response body (if any)

Example:

HTTP/1.1 200 OK
Content-Type: text/xml
Server: gSOAP/2.9

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:EkkoProxy.SystemUtilities.V1">
            .
            .
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

Using WireMock

Ekko Proxy comes with a Mock Editor tool (see below) which manages WireMock mocks that can be created and then used by the proxy instances to serve mocked responses - no coding required. Dynamic responses can be created though, using Handlebars templating, giving you great flexibility.

For more details please see Ekko Proxy WireMock Editor

ekkoproxy WireMock editor

Note the WireMock configuration files created by the Mock Editor can also be copied and used in traditional WireMock based integration test suites, though not all functionality will be available.

Connecting to a proxy

Connecting to an EkkoProxy proxy instance is pretty easy as described in the following sections.

HTTP proxy

Once a EkkoProxy HTTP proxy instance is running on a port then you can configure your application to go through the proxy by repointing the application service endpoints to the hostname and port of where Ekko Proxy instance resides. For example if Ekko Proxy is running on localhost and you created a HTTP proxy on port 3080 then you would use http://localhost:3080.

Forwarding

There can be situations where the port, that an Ekko Proxy is created on, cannot be exposed outside of that machine be it due to firewalls or cloud restrictions etc. In those cases requests can be 'forwarded' to the Ekko proxy/proxies using a special /forward/<port> path as in the example endpoints below:

http://localhost:4040/forward/3080/MyService
or
http://ekkoproxy.mybluemix.net/forward/3080/MyService

Note using this feature will consume threads from the main Tomcat thread pool rather than the individual Ekko Proxy thread pools.

JDBC proxy

How you connect to a EkkoProxy JDBC proxy will depend on your client application's configuration. The legacy approach to loading JDBC drivers (before JDBC version 4 and Java SE 1.6) was to load it manually like below:

Class.forName("com.lcasoft.ekkoproxy.db.jdbc.EkkoProxyDriver");

This should not be necessary however as the ekkoproxyjdbc-1.5.jar will register the driver as a service and you only need to add the jar to your application's classpath.

Once added you can get JDBC database connections by configuring your application with a JDBC URL connection string for the EkkoProxy JDBC proxy instance instead of your actual database. You can connect to the EkkoProxy JDBC proxy instance using HTTP or RMI.

The EkkoProxy JDBC connection string has to start with jdbc:ekkoproxy: which identifies the EkkoProxy JDBC driver. This is then followed by the proxy connection URL starting with the protocol; http, https or rmi. Note that https can only be used if the EkkoProxy application itself has been setup to run on https. After the protocol you must specify the server hostname where EkkoProxy is running followed by a port number. If using http(s) it will be the port number of the EkkoProxy application itself otherwise for rmi its the port of the EkkoProxy JDBC proxy instance. This is then followed by the EkkoProxyJdbc identifier. For rmi connections that is all that is needed and for http(s) you will need to specify the port number of the EkkoProxy JDBC proxy instance last. This is probably best explained with a few example connection URLs as shown below:

DriverManager.getConnection("jdbc:ekkoproxy:http://localhost:4040/EkkoProxyJdbc/2001");
or using RMI:
DriverManager.getConnection("jdbc:ekkoproxy:rmi://localhost:2001/EkkoProxyJdbc");

Dialogs

Expressions test dialog

The Expressions test dialog allows you to verify what your Regex, XPath or JSonPath expressions match and produce the expected results.

In the example below two Normalisation key exclude XPath expressions are to be tested against a SOAP message:

ekkoproxy expressions test dialog, normalise mode

The expressions to be tested in the example are:

  • /Envelope/Header/RequestHeader/networkCode
  • /Envelope/Header/RequestHeader/applicationName

Clicking 'Test It' will result in the below test result:

ekkoproxy expressions test dialog result, normalise mode

This shows the difference with fields removed highlighted in red meaning these fields will not be considered as part of the recorded normalised filename key. In the example above the same result could have been achieved with shorter expressions e.g. //RequestHeader/networkCode or even in one expression e.g. /Envelope/Header or //Header/RequestHeader removing the whole SOAP header instead - that is provided you didn't want to include any of the headers.

It's usually better to be specific unless you know you want to remove all SOAP headers for example for all the messages going though the proxy.

Note not all expressions have to match all messages - if an expression doesn't match it's simply ignored.

Another example would be when testing 'Organising Recordings' reqular expressions as in the example below:

ekkoproxy expressions test dialog, organise mode

The expressions to be tested in this example are:

  1. Channel:\s?(.*)
  2. \"name\"\s?:\s?\"(.*)\"

Clicking 'Test It' will result in the below test result:

ekkoproxy expressions test dialog result, organise mode

The result shows the matches as part of the file path that they will be part of. If the 'Output Directory' is set to say C:\temp then the final recording path would be C:\temp\myChannel\my_username or C:\temp\user\myChannel\my_username if 'Use Request URI in Output Path' was selected and the URI for the service is /user.

Delay settings dialog

The delay settings dialog allows for response delays to be set for requests who's responses are being played back.
The dialog will show requests currently displayed in the messages table or that has been previously set for the proxy.

ekkoproxy delay dialog

To set a delay choose the Request URI and Method, either from the dropdowns or the table, that you want to set/change and use the slider to set a minimum and maximum delay for the particular response.

The max delay slider on the right changes the max delay possible (up to 2 minutes). This also sets the scale of the delay slider itself allowing for either finer or more coarse-grained timings to be set.

Note a license is required for full delay functionality.

Compare dialog

The compare dialog can show the differences between two selected requests or responses. The example below shows the differences between two responses.

ekkoproxy compare dialog

The compare dialog provides either a Split View or Unified View of the differences.

Finally there is an option to compare with or without word-wrapping.

Tools

The tools section of Ekko Proxy brings various useful everyday tools to you securely! You can find many of these tools online but how secure are they? Do you feel comfortable using them and does When working with sensitive data e.g. customer data etc. then it's not secure to use online tools to work with this data.

The following sections describe the Ekko Proxy tools that you can use knowing that your data is safe.

Note you can press Ctrl+Enter / Cmd+Enter within the input field to execute the selected action.

You can press F1 to get details of all the text editor shortcuts. Below is a list of the basic editor shortcuts.

Command Shortcut Key
Cut line (empty selection) Ctrl+X
Copy line (empty selection) Ctrl+C
Paste Ctrl+V
Delete Line Ctrl+Shift+K
Insert Line Below Ctrl+Enter
Insert Line Above Ctrl+Shift+Enter
Move Line Down Alt+Down
Move Line Up Alt+Up
Copy Line Down Shift+Alt+Down
Copy Line Up Shift+Alt+Up
Undo Ctrl+Z
Redo Ctrl+Y
Add Selection To Next Find Match Ctrl+D
Move Last Selection To Next Find Match Ctrl+K Ctrl+D
Undo last cursor operation Ctrl+U
Insert cursor at end of each line selected Shift+Alt+I
Select all occurrences of current selection Ctrl+Shift+L
Select all occurrences of current word Ctrl+F2
Select current line Ctrl+L
Insert Cursor Below Ctrl+Alt+Down
Insert Cursor Above Ctrl+Alt+Up
Jump to matching bracket Ctrl+Shift+\
Indent Line Ctrl+]
Outdent Line Ctrl+[
Go to Beginning of Line Home
Go to End of Line End
Go to End of File Ctrl+End
Go to Beginning of File Ctrl+Home
Scroll Line Down Ctrl+Down
Scroll Line Up Ctrl+Up
Scroll Page Down Alt+PageDown
Scroll Page Up Alt+PageUp
Fold (collapse) region Ctrl+Shift+[
Unfold (uncollapse) region Ctrl+Shift+]
Fold (collapse) all subregions Ctrl+K Ctrl+[
Unfold (uncollapse) all subregions Ctrl+K Ctrl+]
Fold (collapse) all regions Ctrl+K Ctrl+0
Unfold (uncollapse) all regions Ctrl+K Ctrl+J
Add Line Comment Ctrl+K Ctrl+C
Remove Line Comment Ctrl+K Ctrl+U
Toggle Line Comment Ctrl+/
Toggle Block Comment Shift+Alt+A
Find Ctrl+F
Replace Ctrl+H
Find Next Enter
Find Previous Shift+Enter
Select All Occurrences of Find Match Alt+Enter
Toggle Find Case Sensitive Alt+C
Toggle Find Regex Alt+R
Toggle Find Whole Word Alt+W
Toggle Use of Tab Key for Setting Focus Ctrl+M

Compare

The Compare tool allows you to compare two pieces of textual content and view the difference in Split or Unified mode. You can also toggle word-wrap on / off and the content can be formatted in JSON, XML, HTML, Javascript/Typescript, and SQL format.

ekkoproxy compare tool

Encoding

The Encode tool provides Base64, Base64 Url, and Url encode and decode functionality.

ekkoproxy encode / decode tool

Formatting

The Format tool allows you to perform JSON, XML and SQL formatting actions with your choice of preferred indentation level, if any.

ekkoproxy formatting tool

Hashing

The Hash tool provides the ability to perform various hashing algorithms like MD5, various versions of SHA and many others.

ekkoproxy matching tool

The supported hashing algorithms are: Adler-32, CRC-32, CRC-32c, Farm Hash FingerPrint-64, MD5, Murmur3-32, Murmur3-128, SHA-1, SHA-256, SHA-384, SHA-512, and SipHash-2-4.

Note weaker hashing algorithms like MD5 and SHA-1 are no longer considered safe!

JWT

The JWT tool allows you to validate or encode JWT (signed) tokens safely on your own machine i.e. there is no need to use your secret keys on insecure online tools.

ekkoproxy matching tool

The supported JWT signing algorithms are: HMAC-SHA (HS256, HS384, HS512), RSASSA-PKCS (RS256, RS384, RS512), ECDSA (Elliptic Curve - ES256, ES384, ES512), and RSASSA-PSS (PS256, PS384, PS512).

When using HMAC-SHA you can use raw or base64 encoded secret keys selecting the 'Base64 Encoded' checkbox if using the latter.

Keys for signing or validating the JWT tokens can either be provided or generated (licenced version only) using the Generate Secret/Keys button.

Note a license is required for full JWT functionality.

Matching

The Match tool gives you the ability to test Regex JS, Regex Java, XPath or JsonPath expressions.

ekkoproxy matching tool

The flags for Regex JS and Java are:

  • Global (g): matches the pattern multiple times.
  • Ignore case (i): makes the regex case insensitive.
  • Multiline (m): enables multi-line mode. Where ^ and $ match the start and end of the entire string. Without this, multi-line strings match the beginning and end of each line.
  • dotAll (s): short for single line, it causes the . to also match new line characters.
  • Unicode (u): enables support for unicode.

The flags for XPath are:

  • Namespace aware (n): sets whether the parsing of the XML should be aware of namespaces or not. If namespaces aware then the XPath expression must also use namespaces for matching elements that have a namespace.

The Match Details section shows the more details on the regular expression matches and any group matches e.g.:

ekkoproxy matching details tool

WSDL

The WSDL tool allows you to open and view a WSDL definition file and generate mocks from it. The WSDL definition is visualised in a tree structure as can be seen below.

EkkoProxy WSDL tool

A WSDL definition file can be loaded from either a local file (e.g. C:\EkkoProxy\SomeSoapServices.wsdl), a url (e.g. https://www.dataaccess.com/webservicesserver/numberconversion.wso?WSDL) or it can be uploaded via the upload button . The upload button will open the dialog below.

EkkoProxy WSDL tool - upload dialog

You can either click to select a folder or ZIP file containing the WSDL definition file and any potential XSDs or simply drag & drop the files.

Once the WSDL definition is loaded it is possible to generate one or more mocks by clicking the 'Generate Mock...' button. This opens the Generate Mocks dialog as shown below where operations can be selected for which mocks will be generated.

EkkoProxy WSDL tool - generate mocks dialog

Once generated the mock(s) can be found in the Mock Editor where the mock(s) can be modified if / as required.

Note you will need to stop / start any running proxies that you want to pick up the newly generated mock(s).

The SOAP responses are generated based on the 'Message flags' which are all enabled by default. The options are:

  • Build headers (h): the generated SOAP message will contain a SOAP header.
  • Build optional (o): optional elements will be generated in the SOAP message.
  • Example content (e): example content based on the data type will be generated. If disabled a question mark will be generated instead.
  • Type comments (t): a comment will be generated before each element describing it's data type.
  • Value comments (v): for enum type values a comment with all the possible values will be generated before the element.

Before generating mock(s) you can view what the generated SOAP message will look like, based on the message flags above, by clicking the generate request / response icon next to an operation. Request and response nodes will then appear under the operation which shows the generated SOAP message when selected.

OpenAPI

The OpenAPI tool allows you to open and view a OpenAPI definition file and generate mocks from it. The OpenAPI definition is visualised in a tree structure as can be seen below.

EkkoProxy OpenAPI tool

A OpenAPI definition file (JSON or YAML) can be loaded from either a local file (e.g. C:\EkkoProxy\openapi.yaml), a url (e.g. https://petstore3.swagger.io/api/v3/openapi.json) or it can be uploaded via the upload button . The upload button will open the dialog below.

EkkoProxy OpenAPI tool - upload dialog

You can either click to select an OpenAPI YAML or JSON definition file or simply drag & drop one in.

Once the OpenAPI definition is loaded it is possible to generate one or more mocks by clicking the 'Generate Mock...' button. This opens the Generate Mocks dialog as shown below where responses can be selected for which mocks will be generated. If a response supports more than one media type then you can select which one to use.

EkkoProxy OpenAPI tool - generate mocks dialog

Once generated the mock(s) can be found in the Mock Editor where the mock(s) can be modified if / as required.

Note you will need to stop / start any running proxies that you want to pick up the newly generated mock(s). Also note that if generating more than one mock response for the same API then they will have a 'mockstatus' query string added by default (equal to the response code) which is to distinguish between the requests and their corresponding responses. This can be amended in the Mock Editor afterwards if a different request matching mechanism is required.

< Go Back