Generate HTTP API clients in PHP

Zendservice-Api a micro framework API generator Posted by on May 10, 2013

How many times did you write code to perform HTTP calls for an API service? This can be a tedious and repetitive task that can take some time. You need to prepare the HTTP call, check the response code to understand if the call was successfull, extract some information from the Header, format the output and so on.

Some months ago I started to implement the ZF2 component for the new API of OpenStack and I decided to build a class to reduce the amount of code needed for the invocations of HTTP calls, and I wrote the ZendService_Api.

This component can be considered a "micro framework" because the aim is to create a lightweight and complete solution to manage API calls, from a prospective of a PHP client. It uses the ZendHttp component of Zend Framework 2.

Basically, the ZendService_Api component is able to prepare the HTTP call (mapping PHP parameters), to execute the HTTP call (using a ZendHttpClient object), and to convert the HTTP output according to a specific format (JSON, XML or simple text). Moreover, the component is able to manage HTTP status code and assign it as error or successfull operations, according to the API specification.

Installation

You can easly install ZendService_Api component using composer. You need to add the following to your composer.json to enable the ZF2 repository:

"repositories": [
    {
        "type": "composer",
        "url": "https://packages.zendframework.com/"
    }
],

You can then add the ZendService_Api packages to your require list. For example:

"require": {
    "zendframework/zendservice-api": "dev-master"
},

The ZendService_Api package is still in development, you need to use the "dev-master" release. After that, you can run the install command to resolve and download the dependencies:

$ php composer.phar install

Usage

During the development of ZendService_Api component, I tried to simplify the API with a class containing only few methods and simple parameters. I mapped the HTTP calls using the __call magic function of PHP. In this way an API call is managed with a single function (e.g. $api->listUsers(); will execute the listUser HTTP call of an API service). The specification of the HTTP call is provided using a closure or an external PHP file that returns the configuration (using a simple array). You can configure the HTTP call with the following parameters:

  • URL;
  • Headers;
  • Body;
  • Method (GET,POST,PUT,DELETE);
  • HTTP status codes for the successfully operations;
  • format of the output: JSON, XML or nothing (simple text).

You can set the API parameters using the setApi method. This method accepts two parameters: the name of the API and a closure (callback) that returns the configuration with a PHP array.

Let see an example, image you need to consume an authentication API call with a POST HTTP request using a JSON data format with the following parameters: username and password. The HTTP request can be represented as follow:

PUT /v1/auth HTTP/1.1
Host: localhost
Connection: close
Content-Type: application/json
Content-Length: 57

{ 'auth' : { 'username' : 'admin', 'password' : 'test' }}

A valid response will be a 200 HTTP code with a JSON representation of the authentication token. You can to configure the API call using the setApi method in this way (I used the auth name for this API):

use ZendService\Api\Api;

$api = new Api();
$api->setApi('auth', function ($params) {
    return array(
        'uri' => 'http://localhost/v1/auth',
        'header' => array(
            'Content-Type' => 'application/json'
        ),
        'method' => 'POST',
        'body' => json_encode(array(
            'auth' => array(
                'username' => $params[0],
                'password' => $params[1]
            )
        )),
        'response' => array(
            'format' => 'json',
            'valid_codes' => array('200')
        )
    );
});

After that you can execute the API call using the function auth (this function is managed by the magic __call function of PHP):

$result = $api->auth('username', 'password');
if ($api->isSuccess()) {
    if (isset($result['token'])) {
        printf("The authentication token is %sn", $result['token']);
    } else {
        var_dump($result);
    }
} else {
    printf("Error (%d): %sn", $api->getStatusCode(), $api->getErrorMsg());
}

The mapping with the auth arguments and the API specification is managed using the array $params. You have to use the numerical index of the $params to match the order of the arguments in the function. Using the configuration array you can specify all the HTTP data for the API request (headers, body, uri, etc). You can also specify the HTTP status code for the successful requests using the valid_codes parameter in the response section. The format of the HTTP body response is specified by the key ['response']['format']. If you specify the response format the result will be an array.

You can also use a configuration file for the API calls instead of using the setApi method. You need to create a PHP file with the same name of the API call. This file contains the API configuration array. For instance, for the previous example you have to create a auth.php file containing the following array:

return array(
    'uri' => 'http://localhost/v1/auth',
    'header' => array(
        'Content-Type' => 'application/json'
    ),
    'method' => 'POST',
    'body' => json_encode(array(
        'auth' => array(
            'username' => $params[0],
            'password' => $params[1]
        )
    )),
    'response' => array(
        'format' => 'json',
        'valid_codes' => array('200')
    )
);

You need to set the directory containing this configuration file using the setApiPath as follow:

use ZendService\Api\Api;

$api = new Api();
$api->setApiPath('path/to/api/config');
$result = $api->auth('username', 'password');
if ($api->isSuccess()) {
    if (isset($result['token'])) {
        printf("The authentication token is %sn", $result['token']);
    } else {
        var_dump($result);
    }
} else {
    printf("Error (%d): %sn", $api->getStatusCode(), $api->getErrorMsg());
}

If you need to call different API from the same base URL you can use the setUrl function. This function set the base URL and you can use relative URI for the specific API calls, for instance imagine you need to consume the authentication API v.2.0 of OpenStack according to the specification reported here. We can set the following configuration, using the main address as base URL and use relative address for each API call.


use ZendService\Api\Api;

$api = new Api();
$api->setUri('http://identity.api.openstack.org');
$api->setApi('authentication', function ($params) {
    return array(
        'url' => '/v2.0/tokens',
        'header' => array(
            'Content-Type' => 'application/json'
        ),
        'method' => 'POST',
        'body' => json_encode(array(
            'auth' => array(
                'passwordCredentials' => array(
                    'username' => $params[0],
                    'password' => $params[1]
                )
            )
        )),
        'response' => array(
            'format' => 'json',
            'valid_codes' => array('200', '203')
        )
    );
});
$result = $api->authentication('username', 'password');
if ($api->isSuccess()) {
    printf("Authentication token: %sn", $result['access']['token']['id']);
} else {
    printf("Error (%d): %sn", $api->getStatusCode(), $api->getErrorMsg());
}

Note the usage of the relative address in the url parameter of the API configuration.

If you need to pass a query string for an API HTTP call you can use the setQueryParams method of the Api class. For instance, imagine you need to pass the HTTP query string ?auth=strong in the previous example, you can use the following code:

use ZendService\Api\Api;

$api = new Api();
$api->setQueryParams(array( 'auth' => 'strong' ));
$result = $api->authenticate('username', 'password');
if ($api->isSuccess()) {
    printf("OK!n");
} else {
    printf("Error (%d): %sn", $api->getStatusCode(), $api->getErrorMsg());
}

You can reset the query string calling the setQueryParams() function without a parameter.

You can specify a default HTTP headers to be used for all the HTTP calls. For instance, if you need to call a vendor API passing an authentication token using a special header field you can use this feature to set a default headers to be used for all the next API calls.

To set a default headers you can use the setHeaders function, below is reported an example: 

use ZendService\Api\Api;

$api = new Api();
$api->setApiPath('path/to/api/config');
$api->setHeaders(array( 'X-Auth-Token' => 'token' ));
$result = $api->test('foo');
if ($api->isSuccess()) {
    var_dump($result);
} else {
    printf("Error (%d): %sn", $api->getStatusCode(), $api->getErrorMsg());
}

The test API will execute a HTTP request using the headers specified in the test.php configuration file plus the X-Auth-Token header. Basically, the headers specified in the configuration file are merged with the default one specified using the setHeaders function. You can overwrite the default headers using the same header key in the configuration file.

Conclusion

I hope that the ZendService_Api component can help PHP developers to consume HTTP API calls and to write PHP libraries for API vendors with a minimum effort. I'm using this class in some ZendService components of the Zend Framework 2 project and I can say that I have drastically reduced the development time of these libraries.

The actual implementation of ZendService_Api is a working progress version, so if you want to contribute to the development or just give some comments or feedbacks you are more than welcome. To contribute use the official github repository of the component that is https://github.com/zendframework/ZendService_Api.