-
Notifications
You must be signed in to change notification settings - Fork 208
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 several new features we've introduced in the past several months to remove inconsistencies. The key change will be a new data schema to properly integrate 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": [{
"urlPattern": ".",
"delay": 2000
}]
}
},
"meta": {
"hoverflyVersion": "v0.9.0",
"schemaVersion": "v1",
"timeExported": "2016-10-04T16:06:41+01:00"
}
}
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.
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
}
]
}
Along with the new unified schema, we will be introducing a new version of the admin API. This API aims to be more simplified while offering the same functionality. Reducing the number of different ways of importing data into Hoverfly and supporting the new schema.
###GET /api/v2/simulation Gets the simulation data currently in Hoverfly in the form of the unified schema. ###PUT /api/v2/simulation Puts the simulation into Hoverfly and replaces the previous set of data. Accepts the unified schema. ###DELETE /api/v2/simulation Deletes the simulation in Hoverfly ###GET /api/v2/simulation/meta/count Gets a count of each of the different types of objects within the data object of the currently loaded simulation.
{
"count": {
"all": 3,
"recordings": 1,
"templates": 1,
"delays": 1
}
}
###GET /api/v2/hoverfly Gets all configuration for the running instance of Hoverfly.
{
"destination": "github.com",
"identity": "taggable-hoverfly-name",
"middleware": "python ~/middleware.py",
"metrics": {
"counters": {
"capture": 0,
"modify": 0,
"simulate": 0,
"synthesize": 0
}
},
"mode": "simulate"
}
###GET /api/v2/hoverfly/mode Gets the current mode for the running instance of Hoverfly.
{
"mode": "simulate"
}
###PUT /api/v2/hoverfly/mode Puts the new mode and overwrites current mode`` for the running instance of Hoverfly. This accepts JSON that matches the JSON from the GET request. ###GET /api/v2/hoverfly/middleware Gets the current middleware for the running instance of Hoverfly.
{
"middleware": "python ~/middleware.py"
}
###PUT /api/v2/hoverfly/middleware Puts the new middleware and overwrites current middleware for the running instance of Hoverfly. This accepts JSON that matches the JSON from the GET request. ###GET /api/v2/hoverfly/identity Gets the current identity for the running instance of Hoverfly. This is a custom used to help identity an instance of Hoverfly.
{
"identity": "taggable-hoverfly-name"
}
###PUT /api/v2/hoverfly/identity Puts the new identity and overwrites current identity for the running instance of Hoverfly. This accepts JSON that matches the JSON from the GET request. ###GET /api/v2/hoverfly/destination Gets the current destination for the running instance of Hoverfly.
{
"metrics": {
"counters": {
"capture": 0,
"modify": 0,
"simulate": 0,
"synthesize": 0
}
}
}
###PUT /api/v2/hoverfly/destination Puts the new destination and overwrites current destination for the running instance of Hoverfly. This accepts JSON that matches the JSON from the GET request. ###GET /api/v2/hoverfly/metrics Gets the metrics for the running instance of Hoverfly.
{
"metrics": {
"counters": {
"capture": 0,
"modify": 0,
"simulate": 0,
"synthesize": 0
}
}
}
###Current API The current API that Hoverfly has, v1, will remain within Hoverfly for several releases alongside the new v2 API. The v1 API will accept the same JSON it already does, but we will update the POST and PUT endpoints to transform the data and call the v2 endpoints. This means that while both v1 and v2 APIs are in Hoverfly, you can import your v1 shaped data into the v1 API and then export using the v2 API to get the new schema.