Exposing Content via REST

1.3 version

Maintained

Unmaintained

1.2

edit this page

Exposing Content via REST

Exposing Content via REST¶

Many applications need to expose content via REST APIs to partners or to enable integration into other applications. As the CMF is build on top of Symfony2, it's possible to leverage many of the available bundles to provide a REST API for content stored in the CMF. This guide will detail how to provide a read API for your content using the following bundles FOSRestBundle and JMSSerializerBundle.

Installation¶

The ContentBundle provides support for the FOSRestBundle view layer, which is automatically activated by the ContentController when the bundle is available. Furthermore, the FOSRestBundle needs a serializer to generate the REST output. The best choice is the JMSSerializerBundle:

{
    ...
    "require": {
        ...
        "friendsofsymfony/rest-bundle": "1.*",
        "jms/serializer-bundle": "0.13.*"
    }
}

Note

Both bundles are already required by the CreateBundle.

Caution

When using PHPCR-ODM it is necessary to require at least version 1.0.1 of doctrine\phpcr-odm.

Then use Composer to update your projects vendors:

1	$ composer update

Configuring FOSRestBundle¶

Here is an example configuration for the FOSRestBundle.

YAML

fos_rest:
    # configure the view handler
    view:
        force_redirects:
            html: true
        formats:
            json: true
            xml: true
        templating_formats:
            html: true
    # add a content negotiation rule, enabling support for json/xml for the entire website
    format_listener:
        rules:
            - { path: ^/, priorities: [ html, json, xml ], fallback_format: html, prefer_extension: false }

XML

<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">

    <config xmlns="http://example.org/schema/dic/fos_rest">
        <!-- configure the view handler -->
        <view>
            <force-redirect name="html">true</force-redirect>

            <format name="json">true</format>
            <format name="xml">true</format>

            <templating-format name="html">true</templating-format>
        </view>

        <!-- add a content negotiation rule, enabling support for json/xml for the entire website -->
        <format-listener>
            <rule path="^/"
                fallback-format="html"
                prefer-extension="false"
                priorities="html,json,xml"
            />
        </format-listener>
    </config>
</container>

PHP

$container->loadFromExtension('fos_rest', array(
    // configure the view handler
    'view' => array(
        'force_redirects' => array(
            'html' => true,
        ),
        'formats' => array(
            'json' => true,
            'xml' => true,
        ),
        'templating_formats' => array(
            'html' => true,
        ),
    ),
    // add a content negotiation rule, enabling support for json/xml for the entire website
    'format_listener' => array(
        'rules' => array(
            array(
                'path' => '^/',
                'priorities' => array('html', 'json', 'xml'),
                'fallback_format' => 'html',
                'prefer_extension' => false,
            ),
        ),
    ),
));

Using the REST API¶

After you configured the FOSRestBundle, you need to execute the following commands:

curl http://my-cmf.org/app_dev.php -H Accept:application/json
curl http://my-cmf.org/app_dev.php -H Accept:application/xml
curl http://my-cmf.org/app_dev.php -H Accept:text/html

This is all it takes to enable read support via JSON or XML!

The JMS serializer comes with sensible defaults for Doctrine object mappers. However it might be necessary to add additional mapping to more tightly control what gets exposed. See the documentation of the JMS serializer for details.

New in version 1.1: The default response format changed between 1.0 and 1.1 of the ContentBundle. In 1.0 the response is wrapped inside an array/tag. This is no longer the case in 1.1

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.