Exposing Content via REST

1.3 version
Maintained Unmaintained
1.2

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 Symfony, 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 FOSRestBundle and the 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:

1
2
3
4
5
6
7
8
{
    ...
    "require": {
        ...
        "friendsofsymfony/rest-bundle": "^1.7",
        "jms/serializer-bundle": "^1.1"
    }
}

And instantiate the two bundles in your application kernel.

Then use Composer to update your projects vendors:

1
$ composer update

Configuring FOSRestBundle

Here is an example configuration for the FOSRestBundle.

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    # app/config/config.yml
    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
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    <!-- app/config/config.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
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    // app/config/config.php
    $container->loadFromExtension('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,
                ],
            ],
        ],
    ]);
    

Using the REST API

This is all it takes to enable read support via JSON or XML! Test if the setup works as expected with curl:

1
2
3
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

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.

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