Do something about headers...

[maxlinc]

One of the advantages I see about generating contracts as opposed to recording HTTP interactions like a traditional self-initializing fake is we avoid saving either:

• Ephemeral data (data that is likely to change when you re-record, even if it's only been a few minutes)
• Sensitive data

Pacto is good at this for request/response bodies. It doesn't care about changing timestamps, storing passwords, etc., as long as the structure doesn't change. It will only record the actual values if you ask it to. Even then, I'm hoping to store it in a separate file so version control will maintain a clear separation between "changing schema" and "changing data".

Headers are more problematic. Pacto does throw out some ephemeral headers... but it stores the exact data for whatever headers it keeps. The GitHub samples, for example, store Etags:

"Etag": "\"59455ce089e99a07e0b12b9273cd6c8d\""

I would like to keep info about the structure but not data. There are a few ways this could bone done. One might be to just indicate if the header should be present at all (true/false values?). Another option is to allow a subschema for each header. This is powerful, but could make the contracts even harder to read. A third option is to specify a type, which could be basic primitives (string, int, etc), but could also probably include predefined formats URI, email address, UUID, ETag, etc. Another option is to use regexes.

Any creative suggestions?

[jmmercadom]

Just to be sure, you are talking about contract generation, right?

In a partial contract (the one that only has the request part defined) How we could indicate that a response header should be present or not?

I think using subschema for the header is more homogeneous given the response body is also defined using a subschema. This will make the contract more verbose, but not necessary harder to read.

The idea of primitive types sounds interesting, but would be a kind of subschema, or not?

I don't have a strong opinion about this, even leaving the way it is now is acceptable, given in the guide (http://thoughtworks.github.io/pacto/usage/) we recommend to review the generated contract because our heuristics are not foolproof.

[maxlinc]

I'm talking more about how to validate, though generating usable contracts is certainly related.

For example, I was updating the samples in the usage guide to include the rake tasks. If you take the contract produced by the generate sample and use it with rake pacto:generate, then you get something like this:

Validating contracts/api.github.com/repos/thoughtworks/pacto/readme.json
All contracts successfully meta-validated
Validating contracts in directory contracts against host https://api.github.com

readme.json: FAILED!
    * Invalid response header Etag: expected "\"59455ce089e99a07e0b12b9273cd6c8d\"" but received "\"96bf54955b7f71bb7957465552e74bed\""

I might care if the service returns an etag. I might even care if it's a strong or weak etag, but I don't care about the exact value. Not in a contract test, anyways.

There's two parts to the issue, I guess:

• [ ] Ability to validate Headers based on type or schema rather than value
• [ ] Generating contracts that utilize type/schema validation for headers

[maxlinc]

As some inspiration, here's how swagger displays parameters:

See also: https://github.com/wordnik/swagger-core/wiki/Parameters

An OpenStack doc (generated from WADL):

See also: http://apigee.com/docs/console-go/content/wadl-reference

And here's the apiblueprint version: https://github.com/apiaryio/api-blueprint-ast#parameter-section

apiblueprint doesn't seem to group header params in the same section as uri (path or query). The others do.

So we can probably improve things by:

• merge params and headers into one group in the contract definition
• add a style attribute that can be header, or uri if uri, it needs to be in the uriTemplate
• optional primitive json-schema
• variables in the uriTemplate that are not in the params hash are assumed to be optional strings