Re: [cpp-netlib-devel] Comments about the HTTP client interface

[Dean M. B. <mik...@gm...>]

On Thu, Aug 28, 2008 at 1:01 AM, Divye Kapoor <div...@gm...> wrote:
>
>
> On Wed, Aug 27, 2008 at 6:14 PM, Glyn Matthews <gly...@gm...>
> wrote:
>>
>>     using namespace boost::network;
>>     http::request request("http://www.boost.org/");
>>     http::client client_;
>>     http::response response_;
>>     response_ = client_.get(request);
>>
>>
>> What exactly is the role of the client here?  I'm a little confused by the
>> syntax because it reads as though you're trying to make a get request to an
>> HTTP client.  Would it perhaps be better to rename http::client to
>> http::connection?
>
> Currently, I read the above code as:
> 1. frame a request for resource http://www.boost.org/
> 2. Create a client that handles http requests/responses
> 3. Get the resource specified by the request and provide a response.
>

This is the intended interpretation which I was going for. :-)

> However, I do admit that client.head(request) and client.put(request) don't
> seem to be too intuitive in that respect.
>

I had been thinking about that before I even started, and I was
thinking more to provide a compile-time and explicit mapping between
the interfaces and the semantics of the HTTP protocol. More
importantly, I was thinking of alternatives which were:

1. Encapsulating the 'method' into the http::request object.
2. Making the client accept the method as a string.
3. Using the "push" abstraction to convey the action.

I decided against all three because:

For #1:
- This puts undue burden to the request crafting aspect: it makes it
cumbersome to craft requests that you intend to re-use anyway (perform
a HEAD first, and if headers don't fit a certain criteria then do a
GET using the same resource)
- It complicates the http::request implementation by deviating too
much from the message framework/abstraction

For #2:
- It puts the method crafting a 'run-time' action, which introduces
if's and control-flow branches that I would like to be able to
eliminate at compile time otherwise
- Type safety (?) is broken because now the users will be able to
perform 'unsupported' or 'ill-formed' HTTP requests

For #3:
- It's not intuitive (client_ << get(r1, response1) << put(r2,
response2) << delete_(r3, response3))
- It's a lot harder to implement for very little gain syntactically

So given these, I opted to implement the client so that there is a
clear mapping at compile-time of the valid HTTP methods, and a clear
interface regarding the interaction between these methods and the
request objects.

I hope at least this can make it into the documentation or in a
rationale document somehow... ;-)

HTH!

-- 
Dean Michael C. Berris
Software Engineer, Friendster, Inc.