Request Responses Pairs

Hoverfly simulates APIs by matching incoming requests from the client to stored requests. Stored requests have an associated stored response which is returned to the client if the match is successful.

The matching logic that Hoverfly uses to compare incoming requests with stored requests can be configured using Request Matchers.

Request Matchers

When Hoverfly captures a request, it creates a Request Matcher for each field in the request. A Request Matcher consists of the request field name, the type of match which will be used to compare the field in the incoming request to the field in the stored request, and the request field value.

By default, Hoverfly will set the type of match to exactMatch for each field.

See also

There are many types of Request Matcher. Please refer to Request matchers for a list of the types available, and examples of how to use them.

An example Request Matcher Set might look like this:

Field Matcher Type Value
scheme exactMatch “https”
method exactMatch “GET”
destination exactMatch “docs.hoverfly.io”
path exactMatch “/pages/keyconcepts/templates.html”
query exactMatch “query=true”
body exactMatch “”
headers exactMatch  

In the Hoverfly simulation JSON file, this Request Matcher Set would be represented like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
            "request": {
                "scheme": {
                    "exactMatch": "http"
                },
                "method": {
                    "exactMatch": "GET"
                },
                "destination": {
                    "exactMatch": "docs.hoverfly.io"
                },
                "path": {
                    "exactMatch": "/pages/keyconcepts/templates.html"
                },
                "query": {
                    "exactMatch": "query=true"
                },
                "body": {
                    "exactMatch": ""
                },
                "headers": {}
            },

View entire simulation file

The matching strategy that Hoverfly uses to compare an incoming request to a stored request can be changed by editing the Request Matchers in the simulation JSON file.

It is not necessary to have a Request Matcher for every request field. By omitting Request Matchers, it is possible to implement partial matching - meaning that Hoverfly will return one stored response for multiple incoming requests.

For example, this Request Matcher will match any incoming request to the docs.hoverfly.io destination:

1
2
3
4
5
            "request": {
                "destination": {
                    "exactMatch": "docs.hoverfly.io"
                }
            },

View entire simulation file

In the example below, the globMatch Request Matcher type is used to match any subdomain of hoverfly.io:

1
2
3
4
5
            "request": {
                "destination": {
                    "globMatch": "*.hoverfly.io"
                }
            },

View entire simulation file

It is also possible to use more than one Request Matcher for each field.

In the example below, a regexMatch and a globMatch are used on the destination field.

This will match on any subdomain of hoverfly.io which begins with the letter d. This means that incoming requests to docs.hoverfly.io and dogs.hoverfly.io will be matched, but requests to cats.hoverfly.io will not be matched.

1
2
3
4
5
6
            "request": {
                "destination": {
                    "regexMatch": "(\\Ad)",
                    "globMatch": "*.hoverfly.io"
                }
            },

View entire simulation file

See also

There are many types of Request Matcher. Please refer to Request matchers for a list of the types available, and examples of how to use them.

For a practical example of how to use a Request Matcher, please refer to Loose request matching using a Request Matcher in the tutorials section.

Responses

Each Request Matcher Set has a response associated with is. If the request match is successful, Hoverfly will return the response to the client.

1
2
3
4
5
6
7
8
            "response": {
                "status": 200,
                "body": "Response from docs.hoverfly.io/pages/keyconcepts/templates.html",
                "encodedBody": false,
                "headers": {
                    "Hoverfly": ["Was-Here"]
                }
            }

View entire simulation file

Editing the fields in response, combined with editing the Request Matcher set, makes it possible to configure complex request/response logic.

Binary data in responses

Since JSON does not support binary data, binary responses are base64 encoded. This is denoted by the encodedBody field. Hoverfly automatically encodes and decodes the data during the export and import phases.

1
2
                "body": "YmFzZTY0IGVuY29kZWQ=",
                "encodedBody": true,

View entire simulation file