kmfk / hateoas-bundle
Symfony2 Bundle to add Hateoas compliant urls to JMS Serializer
Requires
- php: >=5.4.0
- doctrine/common: >2.4.0
- jms/serializer-bundle: dev-master
Requires (Dev)
- symfony/symfony: dev-master
This package is not auto-updated.
Last update: 2024-10-26 14:59:52 UTC
README
While this works as a simple, drop in bundle for Symfony, you can find a much more full featured library and bundle here:
###Overview
The Hateoas Bundle works with JMS Serializer to allow you to easily add Hateoas compliant resource urls to the JSON output of your REST Api.
There are other similar bundles, but they seemed heavy for my needs. This bundle was designed to work seamlessly with JMS Serializer, with out needing to abstract or obfuscate the serialization of your data.
Currently this bundle only provides Annotations for Resource Linking in your Serialized response.
###Hateoas Bundle Installation
The best method of installation is through the use of composer.
#####Add the bundle to Composer
"require": { "kmfk/hateoas-bundle": "~0.1", }
#####Update AppKernel.php
Add The Hateoas Bundle to your kernel bootstrap sequence
public function registerBundles() { $bundles = array( // ... new Kmfk\Bundle\HateoasBundle\HateoasBundle(), ); return $bundles; }
####Configure the Bundle
The bundle allows you to configure the Rest API host and an optional Path prefix. Your links will be built using these values. If they are not set, the bundle will default to parsing this from the current request.
#app/config.yml
hateoas:
host: http://api.example.com/
prefix: /api/
###Annotations
Once configured, you can use the Annotations provided by this bundle to easily add resource links to your classes and properties.
#src/AcmeBundle/Entity/UserEntity.php use Kmfk/Bundle/HateoasBundle/Annotation/Hateoas; /** * @Hateoas( * name ="self", * href ="/user/{id}/" * params ={"id" = "getId"}, * groups ={"list"}, * type ="absolute" * ) */ class UserEntity { protected $id; public function getId() { return $this->id; } }
####Output:
{ "_links": { "self": { "href": "http://api.example.com/api/user/1/" } } }
###Annotation Reference
####Using Params
You can have multiple tokens in the href
. The params
array should be an associative array
with keys matching the tokens in the path. Methods listed should be methods that exist in the
annotated class.
####Groups
Specifying groups
allow you to control the output of the links based on
Exclusion Groups
####Embedded vs Absolute Links
While absolute
(default value), will allows include the API Host and optional prefix,
embedded
urls live beneath another resource. Setting type to 'embedded
will allow you
to have links like:
{ "_links": { "self": { "href": "http://api.example.com/api/user/1/email/1/" } } }