Awesome

Event API Demo

This repository contains an implementation of the Events API used in my OSCON 2014 talk.

Steps to implement the API

First of all, we need to create a new Symfony2 project. Using Composer, this can be done as follows:

$ composer create-project symfony/framework-standard-edition . "~2.5"

Next, we need to install the HydraBundle by adding it as a dependency

$ composer require ml/hydra-bundle dev-master

registering it in AppKernel.php

// in AppKernel::registerBundles()
$bundles = array(
    // ...
    new ML\HydraBundle\HydraBundle(),
    // ...
);

and importing the routes into routing.yml:

hydra:
    resource: "@HydraBundle/Controller/"
    type:     annotation
    prefix:   /

Now we are ready to implement our simple event API. The first step is to create a bundle

$ php app/console generate:bundle --namespace=ML/EventApiBundle --dir=src \
        --format=annotation --no-interaction

(apart from MLEventApiBundle.php we can delete all files in the src/ML/EventApiBundle folder).

Then we create an entity class representing an event. Doctrine's generator command is quite helpful in this case:

$ php app/console generate:doctrine:entity --entity=MLEventApiBundle:Event --format=annotation

We now need to tell the HydraBundle which fields it should expose and to what concepts they (and the class itself) are mapped. This is as simple as adding annotations in the form of

@Hydra\Expose(iri="http://schema.org/Event")

This is enough information for the HydraBundle to generate a CRUD controller for us:

$ php app/console hydra:generate:crud --entity=MLEventApiBundle:Event \
        --route-prefix=/events/ --with-write --no-interaction

We can now complete the annotation of the Event entity class as we now have the route to generate the URL of an event as well as routes which we can use as operations:

/**
 * Event
 *
 * @ORM\Table()
 * @ORM\Entity
 *
 * @Hydra\Expose(iri="http://schema.org/Event")
 * @Hydra\Id("event_retrieve")
 * @Hydra\Operations( {
 *     "event_replace",
 *     "event_delete"
 * } )
 */
class Event

Assuming the database connection was configured properly during the Symfony2 installation, we can now create the database and generate the tables:

$ php app/console doctrine:database:create
$ php app/console doctrine:schema:create

In our simple example here, we could use the events collection as the main entry point. In most cases, however, a separate entry point makes sense. Thus, we add a new class representing the main entry point and expose it at the root URL (the getEvents() method in EntryPoint is necessary since the HydraBundle doesn't support virtual properties yet).

We can now fire up a server for our API

$ php app/console server:run

and start to interact with it

$ curl http://127.0.0.1:8000/

Of course, we can also install the HydraConsole to navigate the API in the browser.

In order to improve our API a bit and make it more usable in the HydraConsole, we introduce a new EventCollection instead of relying on Hydra's Collection class. This allows us to bind an operation to it.

That's it.