
[![Travis Build Status](https://travis-ci.org/Corion/Future-HTTP.svg?branch=master)](https://travis-ci.org/Corion/Future-HTTP)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/Corion/Future-HTTP?branch=master&svg=true)](https://ci.appveyor.com/project/Corion/Future-HTTP)

# NAME

Future::HTTP - provide the most appropriate HTTP client with a Future API

# SYNOPSIS

    my $ua = Future::HTTP->new();
    my $res = $ua->http_get('http://www.nethype.de/')->then(sub {
        my( $body, $data ) = @_;
        # ... handle the response
        return $body
    })->get();

This module is a wrapper combining [Future](https://metacpan.org/pod/Future) with the API provided
by [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent%3A%3AHTTP). The backend used for the HTTP protocols
depends on whether one of the event loops is loaded.

## Supported event loops

Currently, the following backends are supported:

- [HTTP::Tiny](https://metacpan.org/pod/HTTP%3A%3ATiny)
- [HTTP::Tiny::Paranoid](https://metacpan.org/pod/HTTP%3A%3ATiny%3A%3AParanoid)
- [Mojolicious](https://metacpan.org/pod/Mojolicious)
- [AnyEvent](https://metacpan.org/pod/AnyEvent)
- [IO::Async](https://metacpan.org/pod/IO%3A%3AAsync)

Support
is planned for [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent) and [POE](https://metacpan.org/pod/POE)
but has not materialized yet.

# METHODS

## `Future::HTTP->new()`

    my $ua = Future::HTTP->new();

Creates a new instance of the HTTP client.

## `$ua->is_async()`

Returns true if the selected backend is asynchronous, false if it is
synchronous.

## `$ua->http_get($url, %options)`

    my $res = $ua->http_get('http://example.com/',
        headers => {
            'Accept' => 'text/json',
        },
    )->then(sub {
        my( $body, $headers ) = @_;
        # ... handle the response
    })->get;

Retrieves the URL and returns the body and headers, like
the function in [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent%3A%3AHTTP).

## `$ua->http_head($url, %options)`

    my $res = $ua->http_head('http://example.com/',
        headers => {
            'Accept' => 'text/json',
        },
    )->then(sub {
        my( $body, $headers ) = @_;
        ...
    })->get;

Retrieves the header of the URL and returns the headers,
like the function in [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent%3A%3AHTTP).

## `$ua->http_post($url, $body, %options)`

    my $res = $ua->http_post('http://example.com/api',
        '{token:"my_json_token"}',
        headers => {
            'Accept' => 'text/json',
        },
    )->then(sub {
        my( $body, $headers ) = @_;
        ...
    })->get;

Posts the content to the URL and returns the body and headers,
like the function in [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent%3A%3AHTTP).

## `$ua->http_request($method, $url, %options)`

    my $res = $ua->http_request('PUT' => 'http://example.com/api',
        headers => {
            'Accept' => 'text/json',
        },
        body    => '{token:"my_json_token"}',
    )->then(sub {
        my( $body, $headers ) = @_;
        ...
    })->get;

Posts the content to the URL and returns the body and headers,
like the function in [AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent%3A%3AHTTP).

# SEE ALSO

[Future](https://metacpan.org/pod/Future)

[AnyEvent::HTTP](https://metacpan.org/pod/AnyEvent%3A%3AHTTP) for the details of the API

# REPOSITORY

The public repository of this module is
[https://github.com/Corion/future-http](https://github.com/Corion/future-http).

# SUPPORT

The public support forum of this module is
[https://perlmonks.org/](https://perlmonks.org/).

# BUG TRACKER

Please report bugs in this module via the RT CPAN bug queue at
[https://rt.cpan.org/Public/Dist/Display.html?Name=Future-HTTP](https://rt.cpan.org/Public/Dist/Display.html?Name=Future-HTTP)
or via mail to [future-http-Bugs@rt.cpan.org](https://metacpan.org/pod/future-http-Bugs%40rt.cpan.org).

# AUTHOR

Max Maischein `corion@cpan.org`

# COPYRIGHT (c)

Copyright 2016-2023 by Max Maischein `corion@cpan.org`.

# LICENSE

This module is released under the same terms as Perl itself.
