HTTP Client Manager

Http Client Manager introduces a new Guzzle based plugin which allows you to manage HTTP clients using Guzzle Service Descriptions via YAML, JSON or PHP files, in a simple and efficient way:

"Service descriptions define web service APIs by documenting each operation, the operation's parameters, validation options for each parameter, an operation's response, how the response is parsed, and any errors that can be raised for an operation. Writing a service description for a web service allows you to more quickly consume a web service than writing concrete commands for each web service operation."

You can find here full documentation about Guzzle Services but please keep in mind that the only docs that exist are old and you may need to read the source code at https://github.com/guzzle/guzzle-services.

You will no longer need to write down Http services calls each times specifying endpoints and parameters in a totally decentralized way.

Say goodbye to something like this:

$authToken = $this->httpClient->request('GET', 'http://auth.services.com/token', ['auth' => [$username, $password]]);

$latestPosts = $this->httpClient->request('GET', 'http://api.example.com/posts', ['limit' => '10', 'sort' => 'desc']);

and say welcome to:

Http Services Api definition via *.http_services_api.yml file

example_services:
  title: "Example Services - posts API"
  api_path: "src/api/example_services.yml"
  config:
    base_uri: "http://api.example.com"

auth_services:
  title: "Another Example Services - auth API"
  api_path: "src/api/auth_services.yml"
  config:
    base_uri: "http://auth.services.com"
    debug: 1
    timeout: 5

Overridable Services Api definition via settings.php file

$settings['http_services_api']['example_services'] = [
  'title' => 'Example Services - posts API (Development)',
  'config' => [
    'base_uri' => 'http://api.example.dev',
  ],
];

Ad Hoc client definition via *.services.yml file

services:
  example_api.http_client:
    parent: http_client_manager.client_base
    arguments: ['example_services']

Http Service descriptions

src/api/example_services.yml

name: "[YAML] - ExampleServicesApi"
apiVersion: "2.0"
description: "Client wrapper for the Example Services API."
imports:
  - "resources/posts.yml"

src/api/resources/posts.yml

operations:
  FindPosts:
    httpMethod: "GET"
    uri: "posts"
    summary: "Find all the available posts."
    responseClass: "FindPostsOutput"

  FindPost:
    httpMethod: "GET"
    uri: "posts/{postId}"
    summary: "Find a single post by id."
    responseClass: "Post"
    parameters:
      postId:
        location: "uri"
        description: "Filter posts by id"
        required: true
        type: "string"

models:
  Post:
    type: "object"
    properties:
      userId:
        location: "json"
        type: "integer"
      id:
        location: "json"
        type: "integer"
      title:
        location: "json"
        type: "string"
      body:
        location: "json"
        type: "string"

  FindPostsOutput:
    type: "array"
    location: "json"
    items:
      "$ref": "Post"

Multiple ways to instantiate http clients

// Client instantiation via http_client_manager service factory method.
$client = \Drupal::service('http_client_manager.factory')->get('example_services');

// Client instantiation via service.
$client = \Drupal::service('example_api.http_client');

Multiple ways to execute http requests

// Call method usage.
$latestPosts = $client->call('FindPosts', ['limit' => '10', 'sort' => 'desc']);

// Magic method usage.
$latestPosts = $client->findPosts(['limit' => '10', 'sort' => 'desc']);

You can also create and store (bookmark) predefined requests via web UI as Configuration Entities (exportable via Configuration Manager), and execute them from your code in this way:

// Http Config Request usage via Config Entity static method.
$latestPosts = HttpConfigRequest::load('find_posts')->execute();

// Http Config Request usage via entity type manager.
$latestPosts = $this->entityTypeManager()->getStorage('http_config_request')->load('find_posts')->execute();

A demonstration about request and response alterations can be found Inside the "HTTP Client Manager - Example" module (see "HttpClientManagerExampleSubscriber" class).

Installation

Download via Composer

composer require drupal/http_client_manager

Recommendations

In order to download a module via Composer you need to configure your composer.json file adding drupal packages repository. Otherwise you could run into this kind of error:
Could not find package drupal/http_client_manager at any version for your minimum-stability (dev). Check the package spelling or your minimum-stability

Check links below to learn how to do it:

• Using Composer to install Drupal packages through Drupal.org
• Using Composer in a Drupal project
• Composer template for Drupal projects

Screencast

Try this module online using simplytest.me.

Watch a screencast of the HTTP Client Manager module.