zendservice-api
Abandoned
This component is abandoned and no longer maintained. We recommend using
Guzzle (which has
middleware features that enable API access),
and/or tools built on Guzzle (e.g., Uhura)
that provide generic API access features., (*1)
zendservice-api is a micro HTTP framework to consume generic API calls in PHP.
This framework can be used to create PHP libraries that consume specific HTTP
API using simple configuration array (or files)., (*2)
This project uses the zend-http component of Zend Framework., (*3)
Installation
You can install this component using composer with
following commands:, (*4)
composer require zendframework/zendservice-api
Usage
The ZendService\Api component can be used to facilitate the consume of generic
APIs using HTTP. This library is able to configure the header, method, body, and
query string of a HTTP request according to specific API parameters., (*5)
This mapping is provided using a special PHP configuration array., (*6)
You can specify 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., (*7)
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., (*8)
The HTTP request can be represented as follow:, (*9)
POST /v1/auth HTTP/1.1
Host: localhost
Connection: close
Content-Type: application/json
Content-Length: 57
{ 'auth' : { 'username' : 'admin', 'password' : 'test' }}
You need to configure the API call using the setApi method in this way
(we use the auth name for this API):, (*10)
use ZendService\Api\Api;
$api = new Api();
$api->setApi('auth', function ($params) {
return array(
'url' => '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(
'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):, (*11)
$result = $api->auth('username', 'password');
if ($api->isSuccess()) {
var_dump($result);
} else {
printf("Error (%d): %s\n", $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., (*12)
Using a configuration file
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:, (*13)
return array(
'url' => '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(
'valid_codes' => array('200')
)
);
You need to set the directory containing this configuration file using the
setApiPath as follow:, (*14)
use ZendService\Api\Api;
$api = new Api();
$api->setApiPath('path/to/api/config');
$result = $api->auth('username', 'password');
if ($api->isSuccess()) {
var_dump($result);
} else {
printf("Error (%d): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}
Set the base URL for the API calls
If you need to call different API from the same base URL you can use the
setUri 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 an OpenStack
service with the URL http://identity.api.openstack.org, we can set this address
as base URL and use relative address for each API call., (*15)
use ZendService\Api\Api;
$api = new Api();
$api->setUrl('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(
'valid_codes' => array('200', '203')
)
);
});
$result = $api->authentication('username', 'password');
if ($api->isSuccess()) {
printf("Authenticate!\n");
} else {
printf("Error (%d): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}
Note the use of the relative address in the uri parameter of the API
configuration., (*16)
Query string in the API calls
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:, (*17)
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): %s\n", $api->getStatusCode(), $api->getErrorMsg());
}
You can reset the query string calling the setQueryParams() function without a
parameter., (*18)
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., (*19)
To set a default headers you can use the setHeaders function, below is
reported an example:, (*20)
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): %s\n", $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., (*21)
Wallogit.com
