addHeader doesn't have additive behavior

[Eli Bishop]

This may be more of a documentation issue, but the name addHeader and its current description ("Adds given line to the header") don't accurately describe what the method does. It adds the header if that header name was not already added; otherwise, it replaces the previously added value. The Response contains a Map<String, String> and addHeader is implemented with a simple put.

That means that there is no way to cause the server to return multiple header lines with the same name, even though that is allowed in HTTP. For headers whose semantics allow multiple values, you can get the same effect (from the client's point of view) by sending a single value that is a comma-delimited list. But it's a bit inconvenient to have to do that, when it's so common for HTTP server APIs to support the same "for each header name there can be multiple values" model that HTTP client APIs also support.

If you don't feel that it's desirable to support multiple values, then I would recommend deprecating addHeader, adding a setHeader that does the same thing, and clarifying in the doc comments for both of them that the response will only have the most recent value.