Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Adding the "LINK" http method to the route generation #323

Merged
merged 5 commits into from

3 participants

@OwlyCode

When using the feature described here:

https://github.com/FriendsOfSymfony/FOSRestBundle/blob/master/Resources/doc/5-automatic-route-generation_single-restful-controller.md

You may now declare linkAction(), or linkSomethingAction() in your controller when using an autogenerated route from FosRestBundle.

It works well alone but would be great if merged at the same time with #288 to offer a full LINK method support.

@OwlyCode OwlyCode Adding the "link" method to the route generator.
You may now declare linkAction() in your controller when using an autogenerated route from FosRestBundle.
0326ff4
@mvrhov

I thought that the link method was removed from http specs...

@lsmith77
Owner

isn't there another PR related to link?

@OwlyCode

Yep there's one PR related, it's about adding an annotation for Link method. Concerning the removal of link from the http specs, I effectively can't see it in the http 1.1 specification.

I followed this guide for REST implementation wich is promoting the use of the LINK method.

http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way/

@lsmith77
Owner

i will be working on the topic of HATEOAS in the coming days with @beberlei. i will then decide if we want to support this or not ..

@lsmith77 lsmith77 referenced this pull request
Closed

LINK support #325

@lsmith77
Owner

if you can add some docs i will merge it .. even though LINK is not anymore part of the spec.

@OwlyCode

Nice ! Since the change I made is really tiny (actually a one line change), where can I put the doc ?

@lsmith77
Owner

same place as the docs you linked in the description.

@OwlyCode

I made the changes to the doc, adding the methods to the full example and some documentation at the bottom, where the list of the available http methods lives.

Also, I added the unlink method as it would be inconsistent not to provide it. However I'm aware it is an undiscussed feature. Tell me if you want me to remove it while a choice is made about it.

@lsmith77 lsmith77 closed this
@lsmith77 lsmith77 reopened this
@lsmith77 lsmith77 merged commit a8a9bff into FriendsOfSymfony:master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Nov 11, 2012
  1. @OwlyCode

    Adding the "link" method to the route generator.

    OwlyCode authored
    You may now declare linkAction() in your controller when using an autogenerated route from FosRestBundle.
Commits on Dec 8, 2012
  1. @OwlyCode
  2. @OwlyCode
  3. @OwlyCode
  4. @OwlyCode
This page is out of date. Refresh to see the latest.
View
19 Resources/doc/5-automatic-route-generation_single-restful-controller.md
@@ -105,6 +105,12 @@ class UsersController
public function deleteUserCommentAction($slug, $id)
{} // "delete_user_comment" [DELETE] /users/{slug}/comments/{id}
+
+ public function linkUserAction($slug)
+ {} // "link_user_friend" [LINK] /users/{slug}
+
+ public function unlinkUserAction($slug)
+ {} // "link_user_friend" [UNLINK] /users/{slug}
}
```
@@ -199,6 +205,19 @@ This action also accepts *PATCH* requests to the url */resources/{id}* and is su
Shown as ``UsersController::patchUserAction()`` above.
* **option** - this action accepts *OPTION* requests to the url */resources* and is supposed to return a list of REST
resources that the user has access to. Shown as ``UsersController::userAction()`` above.
+* **link** - this action accepts *LINK* requests to the url */resources/{id}* and is supposed to return nothing but a
+status code indicating that the specified resources were linked. It is used to declare a resource as related to an other one.
+When calling a LINK url you must provide in your header at least one link header formatted as follow :
+``<http://example.com/resources/{id}\>; rel="kind_of_relation"``
+* **unlink** - this action accepts *UNLINK* requests to the url */resources/{id}* and is supposed to return nothing but
+a status code indicating that the specified resources were unlinked. It is used to declare that some resources are not
+related anymore. When calling a UNLINK url you must provide in your header at least one link header formatted as follow :
+``<http://example.com/resources/{id}\>; rel="kind_of_relation"``
+
+Important note about **link** and **unlink**: The implementation of the request listener extracting the resources as entities is not provided
+by this bundle. A good implementation can be found here : http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way/
+It also contains some examples on how to use it. **link** and **unlink** were obsoleted by RFC 2616, RFC 5988 aims to define
+it in a more clear way. Using these methods is not risky, but remains unclear (cf. issues 323 and 325).
### Conventional Actions
View
2  Routing/Loader/Reader/RestActionReader.php
@@ -33,7 +33,7 @@ class RestActionReader
private $namePrefix;
private $parents = array();
- private $availableHTTPMethods = array('get', 'post', 'put', 'patch', 'delete', 'head', 'options');
+ private $availableHTTPMethods = array('get', 'post', 'put', 'patch', 'delete', 'link', 'unlink', 'head', 'options');
private $availableConventionalActions = array('new', 'edit', 'remove');
/**
Something went wrong with that request. Please try again.