Request-Level Client-Side API

Flow-Based Variant

The flow-based variant of the request-level client-side API is presented by the Http().superPool(...) method. It creates a new "super connection pool flow", which routes incoming requests to a (cached) host connection pool depending on their respective effective URIs.

The Flow returned by Http().superPool(...) is very similar to the one from the Host-Level Client-Side API, so the Using a Host Connection Pool section also applies here.

However, there is one notable difference between a "host connection pool client flow" for the host-level API and a "super-pool flow": Since in the former case the flow has an implicit target host context the requests it takes don't need to have absolute URIs or a valid Host header. The host connection pool will automatically add a Host header if required.

For a super-pool flow this is not the case. All requests to a super-pool must either have an absolute URI or a valid Host header, because otherwise it'd be impossible to find out which target endpoint to direct the request to.

Future-Based Variant

Sometimes your HTTP client needs are very basic. You simply need the HTTP response for a certain request and don't want to bother with setting up a full-blown streaming infrastructure.

For these cases Akka HTTP offers the Http().singleRequest(...) method, which simply turns an HttpRequest instance into CompletionStage<HttpResponse>. Internally the request is dispatched across the (cached) host connection pool for the request's effective URI.

Just like in the case of the super-pool flow described above the request must have either an absolute URI or a valid Host header, otherwise the returned future will be completed with an error.

final ActorSystem system = ActorSystem.create();
final Materializer materializer = ActorMaterializer.create(system);

final CompletionStage<HttpResponse> responseFuture =
  Http.get(system)
      .singleRequest(HttpRequest.create("http://akka.io"), materializer);

class Myself extends AbstractActor {
  final Http http = Http.get(context().system());
  final ExecutionContextExecutor dispatcher = context().dispatcher();
  final Materializer materializer = ActorMaterializer.create(context());

  public Myself() {
    receive(ReceiveBuilder
     .match(String.class, url -> {
       pipe(fetch (url), dispatcher).to(self());
     }).build());
  }

  CompletionStage<HttpResponse> fetch(String url) {
    return http.singleRequest(HttpRequest.create(url), materializer);
  }
}