ramblings on PHP, SQL, the web, politics, ultimate frisbee and what else is on in my life
back

What is needed to REST in Symfony2

I think we already have quite a nice toolchain for REST in Symfony2 with Bundles like FOSRestBundle, JMSSerializerBundle, NelmioApiDocBundle, FSCHateoasBundle and HautelookTemplatedUriBundle. What is great about these Bundles is that they are all nicely integrated with each other. But there are still some limitations which should be addressed. The following is not an exhaustive unordered list and also not detailed enough but just something to illustrate where I feel there is still work left:

1) Content type negotiation inside the Routing layer
2) Dynamic content in NelmioApiDocBundle and/or some way to integrate with JMSSerializer exclusion strategies (f.e. so that I can version my API docs together with my API)
3) Dynamic content in FSCHateoasBundle like being able to add Request data into URL patterns or being able to set URLs based on model data etc.
4) Behat Context for testing REST APIs (specifically Context for JSON/XML "assertions)
5) Integrate Behat test reports with NelmioApiDocBundle
6) Wrap up JSONP support
7) Fix open FOSRestBundle issues, especially edge cases in the Routing loader
8) Provide a simple solution to offer token based authentication including API throttling
9) Integrate with the SensioGeneratorBundle (and other RAD solutions like KnpRadBundle)
10) Better support for XML responses in NelmioApiDocBundle when using the "output" support together with JMSSerializer (right now it basically shows you can array like structure which makes sense for JSON only)
11) ..

What I would like is for us to work on creating a prioritized product backlog of all of these features and then do a kickstarter project (anyone used catincan.com yet?) to get funding for this. Ideal candidates for implementing this would imho be Adrien and William but there would be of course also others that could step up here. I imagine with budget for about 3 man months we could provide and incredible experience for the Symfony2 community. If we get 100 companies/people to donate 100 Euros each we would have a very good funding basis for this. I know bringing money into open source is tricky but there are lots of people who we know and trust to produce awesome stuff if they get some time to focus on open source. WDYT?

To put a bit of money where my mouth is .. I would donate 250 Euros for this out of my own pocket ..

Small update (30-05-2013):
There was lack luster interest in such a sponsoring initiative.

3) see https://github.com/TheFootballSocialClub/FSCHateoasBundle/issues/52 and https://github.com/TheFootballSocialClub/FSCHateoasBundle/issues/53
4) see https://github.com/sanpii/behatch-contexts
8) maybe integrate with http://code.google.com/p/varnish-apikey/

update 2 (27-08-2013)

3) It looks like FSCHateoseBundle will be deprecated in favor of BazingaHateoasBundle
6) I finished JSONP support

I have also since switched to using the content type negotiation library that William forked from FOSRest.

Several bugs were fixed but overall there is still very little help to move the Bundle forward and so given my lack of time to push this topic the Bundle kind of is not moving forward. Then again its quite useful in its current state as well.

Comments



Re: What is needed to REST in Symfony2

4) Behat Context for testing REST APIs (specifically Context for JSON/XML "assertions)

Try Behatch ;)

Re: What is needed to REST in Symfony2

there is also a Symfony REST Edition https://github.com/gimler/symfony-rest-edition

Re: What is needed to REST in Symfony2

Another topic we maybe should look into http://jsonapi.org

Re: What is needed to REST in Symfony2

In addition to everything you've said, I'd like to add another: documentation / tutorial. A tutorial on FOSRestBundle - which of course more broadly means that people want to know about REST - is the most asked-for tutorial at KnpUniversity.com (https://knpuniversity.uservoice.com/forums/143666-how-can-we-improve-knpuniversity-/filters/top) . But even for me, I find using all of these tools together in advanced cases very difficult, which means that no tutorial has been created yet. They're individually great, but still a bit low-level, and finding best practices and a full-view of using everything together seems to still be missing.

@lsmith If we made a tutorial on REST in Symfony2, would you also donate your expertise to make sure it's done well? And if not you, who? Our new screencasts all have open source scripts, (even if the video is paid), so anyone can benefit. With a little bit of tech help, we'll run the rest of the way with this :). And really, that goes for a lot of topics... ;)

Cheers!

Re: What is needed to REST in Symfony2

2) Dynamic content in NelmioApiDocBundle and/or some way to integrate with JMSSerializer exclusion strategies (f.e. so that I can version my API docs together with my API)

About the exclusion strategies, that feature is almost done. Checkout the PR here: https://github.com/nelmio/NelmioApiDocBundle/pull/156

Re: What is needed to REST in Symfony2

It seems to me that no one really gets into resource linking. In some apps, I've created a custom form type for giving the ability to just simply pass in an id as you would a hidden form type in common forms.

There are SOO many standards on linking.

The link you posted earlier (http://jsonapi.org) has a clever way of doing it (I'm much more in favor of just having simple ids).

For example... You have a resource at GET /api/user

{
id: 1,
name: "Jordan",
links: {
best_friend: 1
}
}

And if you want to change his best friend... PATCH /api/user/1

[
{ "op": "replace", "path": "/links/author", "value": 2 }
]

Nothing allows for this yet... but this is pretty ugly in itself and no javascript frameworks work with this yet out of the box, so an alternative would be:

PATCH /api/user/1
{

best_friend: 2
}

There's just no clear way of doing it :(