Aside: Bumped into a third project, https://github.com/willdurand/Hateoas . It's somewhat framework-independent. Like FOSRestBundle, it doesn't seem to define default implementations. But it appears more popular than drest on Github, and I've seen the author's name in other contexts.
OK, so I've got a basic example of drest working with the "Country" entity. See also:
- civicrm-symfony – https://github.com/totten/civicrm-symfony/compare/master-drest?expand=1
- civicrm-core – https://github.com/totten/civicrm-core/commit/4f55a312c819a186d62ad693722541850e62c529
One can load countries using a URL like:
http://localhost:8005/civicrm/drest/country/us?format=json
http://localhost:8005/civicrm/drest/country/us?format=xml
Changing the naming strategy (eg country id# vs iso_code) is as simple as changing the annotation.
As far request-routing is concerned, we should be able to add similar annotations to expose any other entity. There's likely to be more work in deciding what entities we want to expose and how.
Initial PR based on HATEOAS and some farmework improvements: https://github.com/civicrm/civicrm-core/pull/2612
This was re-conceived as generic Doctrine support in Civi's API layer.
Aside: For posterity, there's a comparison of REST frameworks at:
https://docs.google.com/spreadsheet/ccc?key=0AujctkQuBowkdDBNOTFqTmpUbVFJV0lGRW5kdGVpVXc&usp=sharing
I did a little digging into drest and FOSRestBundle. Key impressions from documentation:
1. drest aims to be depend on Doctrine but nothing else. FOSRestBundle integrates a lot with Symfony – e.g. to define the format of PUT or POST requests, you create a Symfony Form.
2. drest includes baseline implementations for "GET", "PUT", etc actions. I didn't find a baseline in FOSRestBundle – rather, each action seems to require some custom code. (I was hopeful that we could write a parent-class with some baseline implementations, but it looks like that might not work with FOSRestBundle's naming/routing conventions.)
3. drest includes a code-generator for client-side PHP API. FOSRestBundle works with NelmioApiDocBundle to generate documentation and may have support for "HATEOAS".
In terms of what we want, some first thoughts:
a. We'll want to define a mix of baseline implementations, sharable implementations, and one-off implementations. drest isn't perfect but it's a clearer that it meets this requirement; there's maybe a 50% chance we could do something in FOSRestBundle using a base-class and magic functions – but at that point I think it negates any architectural value provided by FOSRestBundle.
b. Generating documentation & examples seems pretty important.
c. We'll want somewhere to tap in and apply some access-control logic (both generic/baseline logic and custom/one-off logic). Neither framework seems to deal with that head-on, but both allow writing
event listeners and (ii) custom actions, so that seems like a good way in. Tangential: http://symfony.com/doc/current/components/security/authorization.html
d. Civi 4.5 adds support for aggregating API requests – which is cool. I haven't found anything yet in FOSRestBundle or drest which seems comparable.
e. It'll be interesting to play around with the support for relations - to get a better sense for how they work out. Could potentially play the same role as "chaining" in APIv3.