palanik / wrapi
Wrapper for calling Restful API
Installs: 273 896
Dependents: 4
Suggesters: 0
Security: 0
Stars: 5
Watchers: 3
Forks: 1
Open Issues: 0
Requires
- php: >=5.5.0
- guzzlehttp/guzzle: >=6.1.0
- sabre/uri: ^1.0
Requires (Dev)
- internations/http-mock: 0.7.0
- phpunit/phpunit: ^4.0
README
Wrapper for calling Restful API
wrapi
allows you to call HTTP based APIs just like making calls to ordinary php functions.
Installation
Install with Composer
- Update your
composer.json
to requirepalanik/wrapi
package. - Run
composer install
to add wrapi your vendor folder.
{ "require": { "palanik/wrapi": "*" } }
or simply run
composer require palanik/wrapi
Easy Start
Approach I
- Create an array listing all the API endpoints you want to work with.
- Wrap endpoints with
wrapi
. - Call individual endpoints as functions.
See Example Code
Approach II
- Create client object with API Base URL.
- Register API endpoints.
- Call individual endpoints as functions.
See Example Code
Endpoints Array
Declare each endpoint as per the following specifications.
"function_name" => array( "method" => "HTTP_METHOD", // 'GET', 'POST', 'PUT', 'PATCH' or 'DELETE' "path" => "relative/path/to/:api/endpoint" // Can use `Slim`/`express` style path params )
eg. a small set of github.com API
array( "repo" => array( "method" => "GET", "path" => "repos/:owner/:repo" ), "contributors" => array( "method" => "GET", "path" => "repos/:owner/:repo/contributors" ), "languages" => array( "method" => "GET", "path" => "repos/:owner/:repo/languages" ), "tags" => array( "method" => "GET", "path" => "repos/:owner/:repo/tags" ), "branches" => array( "method" => "GET", "path" => "repos/:owner/:repo/branches" ) )
Wrap endpoints
Create a API client object from wrapi
. Provide the base url for the API and the endpoints array.
wrapi
will create a client object with all the necessary functions.
$endpoints = array(...); $client = new wrapi\wrapi('https://api.github.com/', // base url for the API endpoints // your endpoints array ); // client object contains functions to call the API
Register
Register additional API endpoints with the client object with a function name.
$client("zen", array( "method" => "GET", "path" => "zen" ) );
Make the call
Call the functions with arguments.
// This will make GET request to 'https://api.github.com/repos/guzzle/guzzle/contributors' $contributors = $client->contributors('guzzle', 'guzzle'); $zenQuote = $client->zen(); echo "Today's quote: ". $zenQuote;
API
wrapi
is an open ended framework and is not restricted any one or a set of public APIs. All APIs providing HTTP interface to access the endpoints can be wrapped by wrapi
so that you can quickly build your client application.
Endpoint definition
method
& path
/url
are required.
method
- Any one of the HTTP methodspath
- route path to API Endpoint. Supportsexpress
style path paramsquery
- an associative array with name-value pairs. This is optional. Useful where resources are identified via query string parametersurl
- fully qualified uri string to override. Useful when api calls connect to a different endpoints
Client object
The wrapi
object conveniently provides the client interface to the API. Create it by calling new
wrapi\wrapi()
.
The constructor takes the following arguments:
baseURL
- The base url for the API. eg.https://api.github.com/repos/guzzle/guzzle/contributors
endpoints
- The array listing the endpoints of the API. Provide an empty array or a partial list and register endpoints later.options
- Optional parameter.wrapi
uses Guzzle module to connect to API server. Theoptions
parameter is the sameoptions
parameter used inGuzzle``request
.
Register function
Add endpoints to client object.
$client(function_name, endpoint_definition)
function_name
- Alias for the endpoint, also the name of the function to call.endpoint_definition
- Array defining the endpoint.
Function calls
Call the API via the function in the client object. Arguments to the function depend on the API declaration in the endpoints array.
Provide the arguments in the following order:
- named
params
in the url path of the endpoint. eg.$client->contributors('guzzle', 'guzzle') // guzzle (owner) & guzzle (repo) are path params
querystring
as an associative array with name-value pairs. eg.$client->contributors(array("since" => 364) // querystring ?since=364
body
- JSON content forPOST
orPUT
methods. Skip this argument if not required.
Examples
In examples folder.