Upcoming breaking changes

This page is to be used to communicate upcoming changes we intend to introduce to Hoverfly as well as how these new features will impact usage of Hoverfly.

If you have any concerns, questions or feedback regarding any of the changes listed below, please get in contact with us using either Github Issues or by posting in Gitter.

#v0.9.0 The key focus of v.0.9.0 is to consolidate. The past several months we've introduced several new features and new data schemas to back these features. Pre v0.9.0, all of these schemas are slightly disparate and make it more complicated to share and import simulations.

##Schema consolidation In v0.8.1, we introduced a change to the /api/records and the JSON schema, the schema used for importing and exporting data. We changed requests to include a request type field meaning we could have both recordings and templates in the same schema. We believe that all Hoverfly data should exist together. The benefits of this mean that it becomes easier to import all required data to run a simulation as well as making it easier to view and review simulations you have produced.

Below is an example of how we expect the new schema to look.

{
	"data": {
		"pairs": [{
			"response": {
				"status": 200,
				"body": "H4sIAAAAAAAAA92dW5PbNrKA3/MrUErtTlIbjsA76Xjk40viOIkdH082qTylQACU6OFF4WXGcu1D/sN5OlW7f2uanz5wPv0NvYNWFL7grZ588n8Lq2lZn5kAAA==",
				"encodedBody": true,
				"headers": {
					"Cache-Control": [
						"private",
						"max-age=0"
					],
					"Cf-Ray": [
						"2d6f9d5986b306fa-LHR"
					],
					"Connection": [
						"keep-alive"
					],
					"Content-Encoding": [
						"gzip"
					],
					"Content-Type": [
						"text/html; charset=utf-8"
					],
					"Date": [
						"Tue, 23 Aug 2016 15:32:00 GMT"
					],
					"Hoverfly": [
						"Was-Here"
					]
				}
			},
			"request": {
				"requestType": "recording",
				"path": "/news",
				"method": "GET",
				"destination": "bbc.co.uk",
				"scheme": "https",
				"query": "",
				"body": "",
				"headers": {
					"Accept": [
						"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8"
					],
					"Content-Type": [
						"text/plain; charset=utf-8"
					],
					"User-Agent": [
						"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.116 Safari/537.36"
					]
				}
			}
		}, {
			"response": {
				"status": 200,
				"body": "this is a template",
				"encodedBody": false,
				"headers": {
					"Hoverfly": [
						"Was-Here"
					]
				}
			},
			"request": {
				"requestType": "template",
				"destination": "*ycombinator.com"
			}
		}],
		"globalActions": {
			"delays": [{
				"requestType": "recording",
				"path": "/news",
				"delay": 2000
			}]
		}
	},
	"meta": {
		"count": {
			"all": 3,
			"recordings": 1,
			"templates": 1,
			"delays": 1
		},
		"hoverflyVersion": "v0.9.0",
		"schemaVersion": "v1",
		"timeExported": ""
	}
}

The schema now has a new top level property opposite data which is meta. This will be used for keeping useful metadata with the exported simulation. The most important property of meta is the schemaVersion. We plan to version all of our schemas going forwards to better offer compatibility with older simulations.

Within data, we have moved all of the RequestResponsePairs (of both type recording and template) within an array property called pairs. Alongside pairs, we now have a new property called globalActions. Right now, the only global action we support is delays. The reason we have done this is so that we can explore and potentially add new actions which could be applied to RequestResponsePairs, similar to delays, without needing to immediately produce a new version of the schema.

Delays

This new schema also includes changes to delays. The JSON schema originally introduced for delays was fairly minimal and did not conform to the other JSON schemas being used at this time.

{
	"delay": {
		"httpMethod": "POST",
		"urlPattern": ".\/api",
		"delay": 2000
	}
}

This schema is inconsistent. It does not use the same fields as recordings or templates.

The schema we are suggesting for v0.9.0 follows the template schema with optional fields.

{
	"data": {
		"method": "POST",
		"path": "/api",
		"delay": 2000
	}
}

###Replacing regex Another change we intend to make regarding delays and Hoverfly is removing Regex. It is our opinion that Regex isn't always the easiest to work with. The feedback we have received has been people being unsure if their Regex delays are working.

Recently, we introduced a much simpler style of matching to request templates in which you could substitute any number of characters with a UNIX style * wildcard. We feel that this is the most user friendly way to substitute characters.

{
  "data": [
    {
      "method": "POST",
      "path": "/api/*",
      "delay": 2000
    }
  ]
}