Quick Start¶
The most basic example creates and serves a route that echos the content passed in through the URL parameter called name. This route would be accessed through http://www.example.com/hello/myname and would return ‘Hello myname’.
try {
// Instantiate the server (using the default config)
$api = new Apix\Server(require 'config.php');
// Create a GET handler $name is required
$api->onRead('/hello/:name', function($name) {
return array('Hello, ' . $name);
});
$api->run();
} catch (\Exception $e) {
header($_SERVER['SERVER_PROTOCOL'] . ' 500 Internal Server Error', true, 500);
die("<h1>500 Internal Server Error</h1>" . $e->getMessage());
}
Another example using annotations.
try {
// Instantiate the server (using the default config)
$api = new Apix\Server(require 'config.php');
// $type and $stuff are required parameters.
// $optional is not mandatory.
$api->onRead('/search/:type/with/:stuff/:optional',
/**
* Search for things by type that have stuff.
*
* @param string $type A type of thing to search upon
* @param string $stuff One or many stuff to filter against
* @param string $optional An optional field
* @return array
* @api_auth groups=clients,employes,admins users=franck,jon
* @api_cache ttl=12mins tags=searches,indexes
*/
function($type, $stuff, $optional = null) {
// some logic
return $results;
}
);
$api->run();
} catch (\Exception $e) {
header($_SERVER['SERVER_PROTOCOL'] . ' 500 Internal Server Error', true, 500);
die("<h1>500 Internal Server Error</h1>" . $e->getMessage());
}
config.php¶
The following example configuration file is used in the above examples. Details on the function of these options may be found in the /config documentation.
<?php
namespace Apix;
$c = array(
'api_version' => '0.1.0.empty-dumpty',
'api_realm' => 'api.domain.tld',
'output_rootNode' => 'apix',
'input_formats' => array('post', 'json', 'xml'),
'routing' => array(
'path_prefix' => '/^(\/\w+\.\w+)?(\/api)?\/v(\d+)/i',
'formats' => array('json', 'xml', 'jsonp', 'html', 'php'),
'default_format' => 'json',
'http_accept' => true,
'controller_ext' => true,
'format_override' => isset($_REQUEST['_format'])
? $_REQUEST['_format']
: false,
)
);
// Resources definitions
$c['resources'] = array(
'/help/:path' => array(
'redirect' => 'OPTIONS'
),
'/*' => array(
'redirect' => 'OPTIONS',
)
);
// Service definitions
$c['services'] = array(
// Auth examples (see plugins definition)
'auth_example' => function() use ($c) {
$adapter = new Plugin\Auth\Basic($c['api_realm']);
$adapter->setToken(function(array $current) use ($c) {
$users = Service::get('users_example');
foreach ($users as $user) {
if ($current['username'] == $user['username'] && $current['password'] == $user['api_key']) {
Service::get('session', $user);
return true;
}
}
return false;
});
return $adapter;
},
// This is used by the auth_example service defined above.
'users_example' => function() {
return array(
0 => array(
'username' => 'myuser', 'password' => 'mypass', 'api_key' => '12345', 'group' => 'admin', 'realm' => 'www.example.com', 'ips' => '127.0.0.1'
)
);
},
// This is used by the auth_example service defined further above.
'session' => function($user) {
$session = new Session($user['username'], $user['group']);
if (isset($user['ips'])) {
$session->setTrustedIps((array) $user['ips']);
}
$session->addData('api_key', $user['api_key']);
Service::set('session', $session);
}
);
// Plugins definitions
$c['plugins'] = array(
'Apix\Plugin\OutputSign',
'Apix\Plugin\OutputDebug' => array('enable' => DEBUG),
'Apix\Plugin\Tidy',
'Apix\Plugin\Auth' => array('adapter' => $c['services']['auth_example']),
);
// Init is an associative array of specific PHP directives. They are
// recommended settings for most generic REST API server and should be set
// as required. There is most probably a performance penalty setting most of
// these at runtime so it is recommneded that most of these (if not all) be
// set directly in PHP.ini/vhost file on productions servers -- and then
// commented out. TODO: comparaison benchmark!?
$c['init'] = array(
'display_errors' => DEBUG,
'init_log_errors' => true,
'error_log' => '/tmp/apix-server-errors.log',
);
$c['default'] = array(
'services' => array(),
'resources' => array(
'OPTIONS' => array(
'controller' => array(
'name' => __NAMESPACE__ . '\Resource\Help',
'args' => null
),
),
'HEAD' => array(
'controller' => array(
'name' => __NAMESPACE__ . '\Resource\Test',
'args' => null
),
),
)
);
$c['config_path'] = __DIR__;
return $c;