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 Ekko Proxy instance.

ekkoproxy settings screen

The fields on the Proxy Settings page are described below:

Field Description
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 PC / laptop or on a remote server.

Note when the field looses focus, 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.
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.
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 Stub 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.
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 Settings screen can be found below:

ekkoproxy 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.

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.
  • Record - this mode will save all requests and responses going through the proxy to the target server.
  • Playback - in the playback mode Ekko Proxy will respond with a recorded response, if one exists, otherwise it will pass the request to the target server and respond with the servers response.
  • Playback or Record - in the playback or record mode Ekko Proxy will respond with a recorded 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.
  • Playback on Error - this mode will only playback a saved response (provided one exists) if a HTTP error status of 500 or above is received from the target server. If a recording does not exist the original error response is sent.
The different operation modes 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:LCASoft.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:LCASoft.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:LCASoft.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.

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:LCASoft.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:LCASoft.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:LCASoft.Schema.Header">789012</ns2:UserId>
            <ns3:TransactionId xmlns:ns3="urn:LCASoft.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.

Managing a Ekko Proxy instance

Once a Ekko Proxy instance has been created using the Settings page, 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 example below:

ekkoproxy 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.

Fields and functions

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

Field Description
Proxy port, Listener HTTPS
and Description
The proxy port followed by an icon depicting whether the proxy is listening on HTTP or HTTPS 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.
Target HTTPS Icon displaying whether the connection to the target server is using HTTP or HTTPS
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.
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.
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.
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.
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.
Status The HTTP status of the message e.g. 200 OK.
Mode The operation mode used to serve the message e.g. Playback.
Request Url The request URI of the HTTP message.
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.


Example drag & drop of two request recordings on the messages table to send them again:

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.

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.

Request Details

ekkoproxy management screen bottom 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.

Request tab

The request tab displays the message body of the 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.

Response tab

The response tab displays the message body of the 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.

Headers tab

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

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 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

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:LCASoft.SystemUtilities.V1">
            .
            .
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

Using WireMock

Ekko Proxy comes with a Mock Editor tool which manages WireMock mocks that can be created and then used by the proxy instances to serve mocked responses - no coding required.

For more details please see Ekko Proxy 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.

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 requests.

ekkoproxy compare dialog

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

By default 20 lines of context is given though this can easily be changed in the 'Lines of context' dropdown.

Note a license is required for full compare functionality.

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 Ctrl+Enter / Cmd+Enter can be pressed within the input field to execute the selected action.

Compare

The Compare tool allows you to compare two pieces of textual content. The action triggers the Compare dialog showing the result of the compare.

ekkoproxy compare tool

Note a license is required for full compare functionality.

Encoding

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

ekkoproxy encode / decode tool

Formatting

The Formatting tool allows you to do Json and XML formatting actions with your choice of preferred indentation level, if any.

ekkoproxy formatting tool

Hashing

The Hashing 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 machine.

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 Matching tool gives you the ability to test Regex JS, Regex Java, XPath or JsonPath expressions.

ekkoproxy matching tool

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

ekkoproxy matching details tool
< Go Back