HTTP Client Manager

8.x-2.x

• Guzzle version: 6
• Drupal core version: >= 8.4

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.

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).

8.x-1.x

This branch will no longer be supported since the release of Drupal 8.x-4.x and ca be considered deprecated.

Composer requirements:

• "guzzle/guzzle": "^3.9"

Guzzle Http Client project has been splitted into several sub-projects, including Guzzle service descriptions and Guzzle Service Description Loader which can't be installed (actually) via composer due to version compatibility issues.
Once this problem will be fixed, a new version of this module will be created based on Guzzle 6.

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

Standard Download

From your project root:

composer require guzzle/guzzle:^3.9

You can now download http_client_manager via drush:

drush dl -y http_client_manager

Alternatively you can download it by clicking on the "Download" links below and saving the module into the modules/contrib folder within your project.

Screencast

Try this module online using simplytest.me.

Watch a screencast of the HTTP Client Manager module.