Add high-level API with multi-host pooling

[ericmj]

Use the same pooling as db_connection [1] and use Registry for multi-host pooling.

[1] elixir-ecto/db_connection#108

[AndrewDryga]

@ericmj as a follow up to our discussion on CodeBeam I am curious how the interface should look like.

We can have it somewhat similar to :hackney one, but I believe that it can beneficial if we come up with an interface that would make writing and testing API clients easier.

A good example can be found in @michalmuskala gist.

[ericmj]

Sorry, the issue title is a bit confusing. We should start with a pooling implementation and then add an API on top of it. For the sake of the pool we can start with a function request(url, method, headers, body) :: {:ok, status, headers, body} | {:error, term}.

I think the API in the gist is a bit constraining for a general purpose HTTP client, it seems very useful for building API clients though. I think we can add such an API later as a "Builder API", or maybe it would make more sense as an external library since it suggests having multiple adapters.

[michalmuskala]

Yes, the API I imagined in the gist is primarily designed for handling REST APIs, not as a general purpose HTTP client. I also don't think we'll need adapters if we decide to base it on xhttp.

[AndrewDryga]

I'm up for not having adapters too. I see this library replacing HTTPPoison and :hackney and used as a defacto standard.

Exposing request/4 first is a good point, I think it can be public and we can point people to use "the right way" in documentation and proper module structure (eg. exposing general-purpose HTTP client in XHTTP* module and request somewhere deeper than that).

[ryanwinchester]

Yes, a library with an adapter-based approach will really hamper how powerful it could be.

Like, "sorry we can't do AwesomeFeature X, because library C can't support it, even though A and B could"

[ryanwinchester]

I see this library replacing HTTPPoison and :hackney and used as a defacto standard.

I've recently switched from using HTTPoison to using Tesla. Mainly because the plug middleware approach just works very well for me.

I feel like this plug-based approach would work well with Mint's functional conn-based stuff 😇

[zblanco]

or maybe it would make more sense as an external library since it suggests having multiple adapters.

I think it would be pretty neat to use an HTTP Client that conforms to a shared contract on a per-request basis. I can see a different connection pooling implementation on top of Mint being used depending on the Request or external service constraints. This sort of use case is really only possible with a functional architecture like Mint as an HTTP Client.

The separate library would be a shared kernel contract like @michalmuskala 's gist suggests and the coupling that entails, but it would invert the dependencies between API Wrappers and HTTP Clients like Mint. Both HTTP Clients and API Wrappers could depend on something much smaller and less imposing than a library like HTTPoison, Hackney, or Tesla and possibly move API Wrappers towards being more re-usable and maintainable.

[whatyouhide]

I don't think this will happen in Mint. @ericmj, are you ok if we close this issue?