Document how Pact handles query strings

[mefellows]

Background

How Pact stories and serialises query strings is not always obvious. Unlike OpenAPI which has explicit serialisation instructions, Pact does not.

We should update our documentation to provide guidance on how it works. Here's a dump of some things to incorporate into such a document:

Previous Behaviour (<= v2)

Pact previously (versions <= 2) stored the entire query string as an encoded string:

"request": {
  "method": "get",
  "path": "/autoComplete/address",
  "query": "max_results=100&state=NSW&term=80+CLARENCE+ST,+SYDNEY+NSW+2000"
}

Current Behaviour (V3+)

In V3, it was changed to an un-encoded map of keys to list of values format:

"request": {
  "method": "get",
  "path": "/autoComplete/address",
  "query": {
    "max_results": ["100"],
    "state": ["NSW"],
    "term": ["80 CLARENCE ST, SYDNEY NSW 2000"]
  }
}

Unsupported Query String Usages

1. Use of query strings for not passing parameters is not supported:

   example.com/hello?i-love-query-strings! and spaces#not-really
   

2. Custom parameter styles are also not supported, e.g.:

   ?foo:1;bar:2 or ?foo=1,bar=2
   

Special Key Support

• param[] style keys: Simply name the key param[].
• param[0] style keys: Simply name the key param[0], param[1] etc.

Special Value Support

• param=value1,value2 Simply include both values in a single string

How the verifier sends the requests

We use the reqwest library under the hood, uses the foo=a&foo=b style:

<= Spec 2

• String value not percent encoded, HTTP client does encoding, set it as is
• String value not percent encoded, HTTP client does not do encoding, encode it and set it
• String value already percent encoded, HTTP client does not do encoding, set it as is
• String value already percent encoded, HTTP client does do encoding, decode it and set it

> Spec 2

pact file	serialisation
"query": "page=1&size=200"	page=1&size=200
"query": { "page": "1", "size": "200" }	page=1&size=200
"query": { "page": "", "size": "200" }	page=&size=200
"query": { "page": ["1"], "size": ["200"] }	page=1&size=200
"query": { "page": ["1", "2"], "size": ["200"] }	page=1&page=2&size=200
"query": { "page": [], "size": ["200"] }	page=&size=200

TODO: Need to demonstrate raw inputs + encoded outputs here.