General concepts

Exchanges

HTTPolice takes HTTP exchanges (also known as transactions) as input. Every exchange can consist of 1 request and 1+ responses. Usually there is just 1 response, but sometimes there are interim (1xx) responses before the main one.

If you only want to check the request, you can omit responses from the exchange.

On the other hand, if you only want to check the responses, you should still provide the request (if possible), because responses cannot be properly analyzed without it. If you really have no access to the request, you can omit it, but many checks will be disabled.

Reports

The output of HTTPolice is a report containing notices.

Every notice has an ID (such as “1061”) that can be used to silence it, and one of three severities:

error

Something is clearly wrong. For example, a “MUST” requirement of a standard is clearly violated.

Please note that not all errors may be actual problems. Sometimes there is a good reason to violate a standard. Sometimes you just don’t care. You decide which errors to fix and which to ignore. If you don’t want to see an error, you can silence it.

comment
Something is possibly wrong or sub-optimal, but HTTPolice isn’t sure. For example, a “SHOULD” requirement of a standard is clearly violated.
debug
This just explains why HTTPolice did (or did not do) something. For example, when HTTPolice thinks that a response was served from cache, it will report a debug notice to explain why it thinks so. This may help you understand further cache-related notices for that response.

Silencing unwanted notices

You can silence notices that you don’t want to see. They will disappear from reports and from the Python API.

Please note that some notice IDs can stand for a range of problems. For example, most errors in header syntax are reported as notice 1000, so if you silence it, you lose a big chunk of HTTPolice’s functionality.

Silencing globally

When using the httpolice command-line tool, you can use the -s option to specify notice IDs to silence:

$ httpolice -s 1089 -s 1194 ...

Integration methods have similar mechanisms. For example, mitmproxy integration understands the same -s option.

Silencing locally

You can also silence notices on individual messages by adding the special HTTPolice-Silence header to them. Its value is a comma-separated list of notice IDs. For example:

HTTP/1.1 405 Method Not Allowed
Content-Length: 0
HTTPolice-Silence: 1089, 1110

Requests can also silence notices on responses (but not vice-versa) by adding a resp keyword after an ID:

GET /index.html HTTP/1.1
User-Agent: Mozilla/5.0
HTTPolice-Silence: 1033 resp, 1031