This is an outdated version of the Manual. Visit the NEW Manual
 

REST server

In RedBeanPHP 3.5 you can use the new Resty BeanCan Server. The Resty BeanCan server makes it easy to make a REST-like API. To create a Resty BeanCan Server:

    
    $can = new RedBean_Plugin_BeanCanResty;

Whitelist

The first thing to do is to tell RedBeanPHP what methods are allowed per type. To allow users to perform GET and POST but not PUT and DELETE actions for books use:


    $can->setWhitelist(array(
        'book' => array(
            'GET', 'POST'
        )
    ));

For testing purposes, you might want to allow everything:


    $can->setWhitelist('all');

GET request

The Resty BeanCan Server works with a reference bean. For instance a $user. To access or modify a resource you simply pass the path relative to the user and you pass the (HTTP) method:


    $can->handleREST($user, 'book/2', 'GET'); 
    //returns array('result' => array( $property => $value ) )

This will retrieve the own list of the $user and load the book with ID 2. Note that this method will fail if no such book exists in the list. By default, the Resty Can searches in the own list, to search in the shared list, prefix your list with 'shared-':


    $can->handleREST($user, 'site/3/page/4/shared-ad/2', 'GET');

This will retrieve ad 2 on page 4 of site 3.

POST request

To add a new page:


    $can->handleREST($user, 'site/3/page', 'POST', array(
        'bean' => array(
            'title' => 'my new page'
        )
    )); //returns array('result'=>array('id' => 1))

PUT request

To update page 4:


    $can->handleREST($user, 'site/3/page/4', 'PUT', array(
        'bean' => array(
            'title' => 'changed title'
        )
    ));

DELETE request

To delete page 4:


    $can->handleREST($user, 'site/3/page/4', 'DELETE');

GET request for lists

To get a list of pages:


    $can->setWhitelist(array('page'=>'GET')); //you need access to PAGE!
    $can->handleREST($user, 'site/3/page/list', 'GET');

You can predefine SQL snippets:


    $can->setWhitelist(array('page'=>'GET')); //you need access to PAGE!

    $sql = array('page'=>array(
        ' page.number > ? ', array(3)
    ));

    //for shared pages use 'shared-page' as key!

    $can->handleREST($user, 'site/3/page/list', 'GET', array(), $sql);

Custom requests

The BeanCan server also accepts non-rest methods, these will invoke methods on models connected to beans (FUSE):


    $resp = $can->handleREST($user, 
        'site/'.$site->id.'/page/'.$page->id, 
        'mail', array('param'=>array('me')));

    //calls $page->mail('me');

Return values

The handleRest() method returns an array with an error key or a result key. This allows you to do your own post-processing, i.e. convert to JSON or XML. If an error occurs, you get an array like this:


    array(
        'error'=> message,
        'code' => code 
    )

If you want to return beans in a custom REST method, use R::beansToArray().

Error Codes

The error codes in the response array conform to HTTP error codes: exceptions generate a 500 code, if the bean is not on the whitelist you get a 403 code, if the bean cannot be found you get a 404 code other errors (syntax) return a 400 code.

Why is PUT used to UPDATE beans?

According to the HTTP/1.1 specification, PUT and DELETE need to be idempotent. PUTTING a bean 3 times with the same payload will have the same effect as PUTTING that bean just once. Same applies to DELETE and GET. On the other hand, POSTING a bean X times creates X new beans, so the HTTP POST method is NOT idempotent.

Don't forget to configure the whitelist!

Legacy REST Server (only get)

This server is now deprecated. In RedBeanPHP 3.0 the BeanCan server also responds to RESTFul GET requests. To setup a REST server with beancan:


    $server = new RedBean_BeanCan();
    $server->handleRESTGetRequest('/book/2'); //returns book with ID 2
    $server->handleRESTGetRequest('/book'); //returns books

RedBeanPHP

 
 

RedBeanPHP Easy ORM for PHP © 2024 Gabor de Mooij and the RedBeanPHP community - Licensed New BSD/GPLv2