RESTful API server for structured and self-documenting resources over JSON, XML, ...

0.3.10 2015-06-02 16:00 UTC


Latest Stable Version Build Status Code Quality Code Coverage License

APIx is a (micro-)framework to build RESTful Web services. It will run alognside your existing framework/application with minimum fuss.

Some of its features:

  • Supports many data inputs such as GET/POST parameters, XML, JSON, CSV, ...
  • Provides various output representation such as XML, JSONP, HTML, PHP, ...
  • Provides on-demand resources documention, using GET /help or 'OPTIONS'.
  • Uses annotations to document and set service behaviours.
  • Handles most HTTP methods, including PUT, DELETE, HEAD, OPTIONS and PATCH (TRACE to some extend).
  • Bundle with many plugins and adapters for Authentification and ACL, caching...
  • Follows the standards such as rfc2616 rfc2616, rfc2617 rfc2617, rfc2388 rfc2388, rfc2854 rfc2854, rfc4627 rfc4627, rfc4329 rfc4329, rfc2046 rfc2046, rfc3676 rfc3676, rfc3023 rfc3023, etc...
  • Provides method-override usign X-HTTP-Method-Override (Google recommendation) and/or using a query-param (customisable).
  • Supports content negotiation (which can also be overriden).
  • Take advantages of network caches -- supports HEAD test.
  • Available as a standalone PHAR file, or via Composer or as a PEAR pear package.
  • Continuous integration against PHP 5.3, 5.4, 5.5 and 5.6.
  • Read the documentation!


  • Self-generated API resources testing.
  • Add support for WSDL 2.0 / WADL.
  • Eventually SOAP (and XML_RPC) bridging.

Feel free to comment, send pull requests and patches...

Basic usage

    require 'apix.phar';

    // Instantiate the server (using the default config)
    $api = new Apix\Server;

    // Create a GET handler $name is required
    $api->onRead('/hello/:name', function($name) {
        return array('Hello ' . $name);


Another example using annotations.

    // $type and $stuff are required parameters.
    // $optional is not mandatory.
         * 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;


Advanced usage


A route defines the path to a resource, once matched the corresponding resource's controller and dedicated handlers are invoked.

Any returned value emanating from a resource's controller, generally an associative array, will become the main subject of the response.

Essentially, a route is made of:

  1. A route controller that corresponds to a HTTP header method:
    onCreate()   ->   POST          |        onModify()   ->   PATCH
    onRead()     ->   GET           |        onHelp()     ->   OPTIONS
    onUpdate()   ->   PUT           |        onTest()     ->   HEAD
    onDelete()   ->   DELETE        |        onTrace()    ->   TRACE
  1. A route path corresponding to a Request-URI.
    • It may represent a specific and static resource entity, such as:
    • It may also be dynamic, and may include one or many variables indicated by a colon :, such as:

Controller definitions

A resource controller may be declared as either:

  • a public method from some user defined classes,
  • a closure/lambda function, defined at runtime (Sinatra style).

It will use:

  • variable name to inherit values from the route's path, e.g. $name inherited from /category/:name.

  • type hinting to inject any of the current scope Apix's objects, e.g. Request, Response, etc...

    See Apix's own [Documentation] apixdoc for what's available.

Here is an example showing these in context:

    $api->onRead('/category/:name', function(Request $request, $name) {

        // retrieve a named param
        $page = (int) $request->getParam('page');

        // retrieve the body params, parsed from XML, JSON, ...
        $params = $request->getBodyParams();


        return $list_defs;


Check the inline comments in the config.dist.php file shipped with the distribution.


To boostrap an Apix server, add the required file and create an instance of the Apix\Server.

A dedicated configuration file can be injected to an Apix server:

        require 'apix.phar';

        $api = new Apix\Server(require 'my_config.php');


PHAR Console

Apix PHAR distribution contains a built-in console. Try invoking the api.phar file on the command line as follow:

$ php apix.phar --help

Web server configuration

Use one of the vhost file provided within the distribution and follow the relevant instructions provided in the comments to set your web server environement.

TODO: Add ngynx and lighttpd files to the distrib.


Annotations can be used to define many aspects of a resource entity.

Here is a self explanatory example:

             * Retrieve the named sotfware
             * Anyone can use this resource entity to download apps. If no
             * version is specified the latest revision will be returned.
             * @param     string    $app        The name of the app
             * @param     string    $version    The version number.
             * @return    array     A response array.
             * @api_auth  groups=public
             * @api_cache ttl=1week tags=downloads
            function($app, $version=null) {
                // ...
                return array(
                    $app => 'the version string of software.'

             * Upload a new software
             * Admin users use this resource entity to upload new software.
             * @param      Request  $request   The Server Request object.
             * @param      string   $software
             * @return     array    A response array.
             * @api_auth   groups=admin users=franck
             * @api_cache  purge=downloads
            function(Request $request, $software) {
                // ...



Apix requires PHP 5.3 or later.

  • [Phar file] phar (recommended)

  • If you are creating a component that relies on Apix locally:

    • either update your composer.json file:

        "require": {
          "apix/apix": "0.3.*"
    • or update your package.xml file as follow:

  • For a system-wide installation using PEAR:
    sudo pear channel-discover pear.ouarz.net
    sudo pear install --alldeps ouarz/apix

For more details see pear.ouarz.net.


To run the unit test suite simply run phpunit from within the main dir.

Integration and functional tests are also available in the src/tests.


APIx is licensed under the New BSD license -- see the LICENSE.txt for the full license details.

  _|_|    _|_|    _|     _|      _|
_|    _| _|    _|         _|    _|
_|    _| _|    _| _|        _|_|
_|_|_|_| _|_|_|   _| _|_|   _|_|
_|    _| _|       _|      _|    _|
_|    _| _|       _|     _|      _|