[WIP] Add REST API cookbook entry

[damienalexandre]

Q	A
Doc fix?	no
New docs?	yes
Applies to	all (or 2.3+)
Fixed tickets

Following this thread on the resting-with-symfony ML,
we think adding a cookbook entry about REST API could be a good thing. FOSRestBundle is not the only response here and I think it's important to get some basics skills before using such a bundle.

At the moment I only have a quick plan,
but we need to choose what we should expose in this documentation for the update / create actions.

• using the form component to update the resource via "application/x-www-form-urlencoded"?
• using the serializer to parse a payload?
• using something like the RestBundle BodyListener and the JsonToFormDecoder?

Also we need to draw the line somewhere about RESTful. I do not think we should tell in this cookbook how to implement everything (hypermedia and such).

Please ping me if you have time to help, I will give you write access to the branch directly.

[lsmith77]

should we base the cookbook entry around the REST edition? ie. take the examples from there, so that people can then always get a live working version of what is explained here?

https://github.com/gimler/symfony-rest-edition

[xabbuh]

should we base the cookbook entry around the REST edition? ie. take the examples from there, so that people can then always get a live working version of what is explained here?

https://github.com/gimler/symfony-rest-edition

👍

[cordoval]

way -> ways

[wouterj]

Big 👍 !

I really like to include more of these articles which try how to solve a certain problem and then also describe how a 3th party project can be used to solve it easier in some cases.

One concern I have (though my rest knowledge is close to zero) is that this topic is too big for one article. Maybe splitting this article into multiple articles in a new cookbook section called "Rest" (or more describing) will be easier to read and reference too?

[willdurand]

should we base the cookbook entry around the REST edition? ie. take the examples from there, so that people can then always get a live working version of what is explained here?

https://github.com/gimler/symfony-rest-edition

👍

[willdurand]

I'd rather not include any reference to Doctrine.

[aferrandini]

👍
As @willdurand mention, I think we have to remove Doctrine and all other specific terms. Probably we could write another cookbook or extend this explaining more detailed cases.

[weaverryan]

Yep, I also like the idea of building the examples that are shown in the REST edition. It would be almost a tutorial to how those examples were built. And I also agree with Wouter that we should probably break things into as small pieces as possible. The scope of this is HUGE, let's try to tackle it in small pieces, based on what people probably ask for the most (e.g. "How do I properly handle POST'ed input", "how should I document my API", "How do can I turn an entity into JSON and include a generated URL in it", "How can I handle authentication via an API token?").

We should be careful not to duplicate logic inside of other bundles (e.g. JMSSerializerBundle), but the transition should be smooth. If we were talking about how to do some serialization stuff, we should go through the steps of getting it all setup here, and then link to the main bundle's docs for more specific information (without being too unhelpful). I see these entries as the missing "glue" between all the different pieces.

Very excited about this!

[lsmith77]

BTW somewhat related to this .. at Liip we were experimenting with creating a RAD Edition that would feature multiple open PRs .. one adding certain Bundles and additional PRs on top of those PRs providing examples how to use those Bundles. Here is such an example PR:
https://github.com/liip/symfony-rad-edition/pull/36

The idea here is that it is easier to validate that the code still runs. And number two its easier for people to play with this.

This is not necessarily an alternative to cookbook entries .. but maybe a complementary approach.

/cc @weaverryan

[lsmith77]

Oh and another semi related comment .. @dantleech has created a sphinx extension to generate Behat features from reST documents https://github.com/dantleech/sphinx-behat

[dantleech]

Well, I am in the process of creating it, Its a way off from working yet :)

[weaverryan]

@lsmith77 I like the idea of creating some examples that are as annotated as possible so you can just dive into the code. As you said, documentation could be used to augment that - a story that guides you through what the thinking was, where to look first, second and third - but offload additional details to looking at the code/comments (to avoid duplication). 👍 for that.

[lsmith77]

another good starting point is @couac's and my slide deck from SymfonyCon:
http://friendsofsymfony.github.io/slides/build-awesome-rest-apis-with-symfony2.html

[willdurand]

s/couac/willdurand :p

[lsmith77]

never made the switch :)

also another approach is to ask people to submit blog posts on the topic that they found useful to see what people actually need to hear about.

for example:
http://blog.marcinbudny.com/2014/02/sending-binary-data-along-with-rest-api.html

[wouterj]

@damienalexandre did you make any progress on this PR? Otherwise, it might be better to create an issue to discuss how this will look and which way to choose and then start a PR.

[damienalexandre]

Yes sorry I didn't get the time to progress on this topic,
and I'm still looking for a consensus about The Right Way© to do a Rest API with SF2;
I think the main question is "should we expose RestBundle right away or should we do it manually from top to bottom first".

I'm ok to close this PR & move the discussion in a new issue.

[timglabisch]

@damienalexandre may we should do both. why not rename this to "Add REST API USING FosRestBundle cookbook entry" and create a new issue to solve the same using vanilla Symfony?

[wouterj]

Closing in favor of a new issue: #5260

[timglabisch]

why a rest controller must be able?this is confusing, it's up to the controller / router what kind of verbs are supportet.