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.x, and 7.x.
• Read the documentation!

Todo:

• 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...

<?php
    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);
    });

    $api->run();

Another example using annotations.

    // $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();

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

2. A route path corresponding to a Request-URI.
   • It may represent a specific and static resource entity, such as:

     /search/france/paris

   • It may also be dynamic, and may include one or many variables indicated by a colon :, such as:

     /search/:country/:city

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:

    <?php
        require 'apix.phar';

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

        $api->run();

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

$ php apix.phar --help

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:

    <?php
        $api->onRead('/download/:app/version/:version',
            /**
             * 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.'
                );
            }
        );

        $api->onCreate('/upload/: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) {
                // ...
            }
        );

        $api->run();

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:

    <dependencies>
      <required>
        <package>
          <name>apix_server</name>
          <channel>pear.ouarz.net</channel>
          <min>1.0.0</min>
          <max>1.999.9999</max>
        </package>
      </required>
    </dependencies>

• 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.

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