Translated version of slides used for my talk about creating RESTful APIs with Symfony2 at Italian SymfonyDay (Rome, October 18th 2013)

1. REST in practice
with Symfony2

2. @dlondero

6. OFTEN...

7. Richardson Maturity Model

8. NOT
TALKING
ABOUT...

9. Level 0
POX - RPC

10. Level 1
RESOURCES

11. Level 2
HTTP VERBS

12. Level 3
HYPERMEDIA

13. TALKING
ABOUT HOW
TO DO

14. WHAT WE NEED
!
•symfony/framework-standard-edition
!
•friendsofsymfony/rest-bundle
!
•jms/serializer-bundle
!
•nelmio/api-doc-bundle

15. //src/Acme/ApiBundle/Entity/Product.php;!
!
use SymfonyComponentValidatorConstraints as Assert;!
use DoctrineORMMapping as ORM;!
!
/**!
* @ORMEntity!
* @ORMTable(name="product")!
*/!
class Product!
{!
/**!
* @ORMColumn(type="integer")!
* @ORMId!
* @ORMGeneratedValue(strategy="AUTO")!
*/!
protected $id;!
!
!
!
/**!
* @ORMColumn(type="string", length=100)!
* @AssertNotBlank()!
*/!
protected $name;!
/**!
* @ORMColumn(type="decimal", scale=2)!
*/!
protected $price;!
/**!
* @ORMColumn(type="text")!
*/!
protected $description;!

16. CRUD

17. Create
HTTP POST

18. Request
POST /products HTTP/1.1!
Host: acme.com!
Content-Type: application/json!
!
{!
"name": "Product #1",!
"price": 19.90,!
"description": "Awesome product"!
}!

19. Response
HTTP/1.1 201 Created!
Location: http://acme.com/products/1!
Content-Type: application/json!
!
{!
"product": {!
"id": 1,!
"name": "Product #1",!
"price": 19.9,!
"description": "Awesome product"!
}!

20. //src/Acme/ApiBundle/Resources/config/routing.yml!
!
acme_api_product_post:!
pattern: /products!
defaults: { _controller: AcmeApiBundle:ApiProduct:post,
_format: json }!
requirements:!
_method: POST

21. //src/Acme/ApiBundle/Controller/ApiProductController.php!
!
use FOSRestBundleViewView;!
!
public function postAction(Request $request)!
{!
$product = $this->deserialize(!
'AcmeApiBundleEntityProduct',!
$request!
);!
!
!
!
!
!
if ($product instanceof Product === false) {!
return View::create(array('errors' => $product), 400);!
}!
$em = $this->getEM();!
$em->persist($product);!
$em->flush();!
$url = $this->generateUrl(!
'acme_api_product_get_single',!
array('id' => $product->getId()),!
true!
);!
$response = new Response();!
$response->setStatusCode(201);!
$response->headers->set('Location', $url);!
return $response;!
}

22. Read
HTTP GET

23. Request
GET /products/1 HTTP/1.1!
Host: acme.com

24. Response
HTTP/1.1 200 OK!
Content-Type: application/json!
!
{!
"product": {!
"id": 1,!
"name": "Product #1",!
"price": 19.9,!
"description": "Awesome product"!
}!

25. public function getSingleAction(Product $product)!
{!
return array('product' => $product);!
}

26. Update
HTTP PUT

27. Request
PUT /products/1 HTTP/1.1!
Host: acme.com!
Content-Type: application/json!
!
{!
"name": "Product #1",!
"price": 29.90,!
"description": "Awesome product"!
}!

28. Response
HTTP/1.1 204 No Content!
!
HTTP/1.1 200 OK!
Content-Type: application/json!
!
{!
"product": {!
"id": 1,!
"name": "Product #1",!
"price": 29.90,!
"description": "Awesome product"!
}!

29. //src/Acme/ApiBundle/Controller/ApiProductController.php!
!
use FOSRestBundleControllerAnnotationsView as RestView;!
!
/**!
* @RestView(statusCode=204)!
*/!
public function putAction(Product $product, Request $request)!
{!
$newProduct = $this->deserialize(!
'AcmeApiBundleEntityProduct',!
$request!
);!
!
if ($newProduct instanceof Product === false) {!
return View::create(array('errors' => $newProduct), 400);!
}!
!
$product->merge($newProduct);!
!
$this->getEM()->flush();!
}

30. Partial Update
HTTP PATCH

31. Request
PATCH /products/1 HTTP/1.1!
Host: acme.com!
Content-Type: application/json!
!
{!
"price": 39.90,!
}!

32. Response
HTTP/1.1 204 No Content!
!
HTTP/1.1 200 OK!
Content-Type: application/json!
!
{!
"product": {!
"id": 1,!
"name": "Product #1",!
"price": 39.90,!
"description": "Awesome product"!
}!

33. //src/Acme/ApiBundle/Controller/ApiProductController.php!
!
use FOSRestBundleControllerAnnotationsView as RestView;!
!
/**!
* @RestView(statusCode=204)!
*/!
public function patchAction(Product $product, Request $request)!
{!
$validator = $this->get('validator');!
!
$raw = json_decode($request->getContent(), true);!
!
$product->patch($raw);!
!
if (count($errors = $validator->validate($product))) {!
return $errors;!
}!
!
$this->getEM()->flush();!
}

34. Delete
HTTP DELETE

35. Request
DELETE /products/1 HTTP/1.1!
Host: acme.com

36. Response
HTTP/1.1 204 No Content

37. //src/Acme/ApiBundle/Controller/ApiProductController.php!
!
use FOSRestBundleControllerAnnotationsView as RestView;!
!
/**!
* @RestView(statusCode=204)!
*/!
public function deleteAction(Product $product)!
{!
$em = $this->getEM();!
$em->remove($product);!
$em->flush();!
}

38. Serialization

39. use JMSSerializerAnnotation as Serializer;!
!
/**!
* @SerializerExclusionPolicy("all")!
*/!
class Product!
{!
/**!
* @SerializerExpose!
* @SerializerType("integer")!
*/!
protected $id;!
!
!
!
/**!
* @SerializerExpose!
* @SerializerType("string")!
*/!
protected $name;!
/**!
* @SerializerExpose!
* @SerializerType("double")!
*/!
protected $price;!
/**!
* @SerializerExpose!
* @SerializerType("string")!
*/!
protected $description;!

40. Deserialization

41. //src/Acme/ApiBundle/Controller/ApiController.php!
!
protected function deserialize($class, Request $request, $format = 'json')!
{!
$serializer = $this->get('serializer');!
$validator = $this->get('validator');!
!
try {!
$entity = $serializer->deserialize(!
$request->getContent(),!
$class,!
$format!
);!
} catch (RuntimeException $e) {!
throw new HttpException(400, $e->getMessage());!
}!
!
if (count($errors = $validator->validate($entity))) {!
return $errors;!
}!
!
return $entity;!
}!

42. Testing

44. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
use LiipFunctionalTestBundleTestWebTestCase;!
!
class ApiProductControllerTest extends WebTestCase!
{!
public function testPost()!
{!
$this->loadFixtures(array());!
!
$product = array(!
'name' => 'Product #1',!
'price' => 19.90,!
'description' => 'Awesome product',!
);!
!
$client = static::createClient();!
$client->request(!
'POST', !
'/products', !
array(), array(), array(), !
json_encode($product)!
);!
!
$this->assertEquals(201, $client->getResponse()->getStatusCode());!
$this->assertTrue($client->getResponse()->headers->has('Location'));!
$this->assertContains(!
"/products/1", !
$client->getResponse()->headers->get('Location')!
);!
}!

45. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
public function testPostValidation()!
{!
$this->loadFixtures(array());!
!
$product = array(!
'name' => '',!
'price' => 19.90,!
'description' => 'Awesome product',!
);!
!
$client = static::createClient();!
$client->request(!
'POST', !
'/products', !
array(), array(), array(), !
json_encode($product)!
);!
!
$this->assertEquals(400, $client->getResponse()->getStatusCode());!
}!

46. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
public function testGetAction()!
{!
$this->loadFixtures(array(!
'AcmeApiBundleTestsFixturesProduct',!
));!
!
$client = static::createClient();!
$client->request('GET', '/products');!
!
$this->isSuccessful($client->getResponse());!
$response = json_decode($client->getResponse()->getContent());!
!
$this->assertTrue(isset($response->products));!
$this->assertCount(1, $response->products);!
!
$product = $response->products[0];!
$this->assertSame('Product #1', $product->name);!
$this->assertSame(19.90, $product->price);!
$this->assertSame('Awesome product!', $product->description);!
}

47. //src/Acme/ApiBundle/Tests/Fixtures/Product.php!
!
use AcmeApiBundleEntityProduct as ProductEntity;!
!
use DoctrineCommonPersistenceObjectManager;!
use DoctrineCommonDataFixturesFixtureInterface;!
!
class Product implements FixtureInterface!
{!
public function load(ObjectManager $em)!
{!
$product = new ProductEntity();!
$product->setName('Product #1');!
$product->setPrice(19.90);!
$product->setDescription('Awesome product!');!
!
$em->persist($product);!
$em->flush();!
}!
}!

48. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
public function testGetSingleAction()!
{!
$this->loadFixtures(array(!
'AcmeApiBundleTestsFixturesProduct',!
));!
!
$client = static::createClient();!
$client->request('GET', '/products/1');!
!
$this->isSuccessful($client->getResponse());!
$response = json_decode($client->getResponse()->getContent());!
!
$this->assertTrue(isset($response->product));!
$this->assertEquals(1, $response->product->id);!
$this->assertSame('Product #1', $response->product->name);!
$this->assertSame(19.90, $response->product->price);!
$this->assertSame(!
'Awesome product!', !
$response->product->description!
);!
}

49. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
public function testPutAction()!
{!
$this->loadFixtures(array(!
'AcmeApiBundleTestsFixturesProduct',!
));!
!
$product = array(!
'name' => 'New name',!
'price' => 39.90,!
'description' => 'Awesome new description'!
);!
!
$client = static::createClient();!
$client->request(!
'PUT', !
'/products/1', !
array(), array(), array(), !
json_encode($product)!
);!
!
$this->isSuccessful($client->getResponse());!
$this->assertEquals(204, $client->getResponse()->getStatusCode());!
}

50. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
/**!
* @depends testPutAction!
*/!
public function testPutActionWithVerification()!
{!
$client = static::createClient();!
$client->request('GET', '/products/1');!
$this->isSuccessful($client->getResponse());!
$response = json_decode($client->getResponse()->getContent());!
!
$this->assertTrue(isset($response->product));!
$this->assertEquals(1, $response->product->id);!
$this->assertSame('New name', $response->product->name);!
$this->assertSame(39.90, $response->product->price);!
$this->assertSame(!
'Awesome new description', !
$response->product->description!
);!
}

51. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
public function testPatchAction()!
{!
$this->loadFixtures(array(!
'AcmeApiBundleTestsFixturesProduct',!
));!
!
$patch = array(!
'price' => 29.90!
);!
!
$client = static::createClient();!
$client->request(!
'PATCH', !
'/products/1', !
array(), array(), array(), !
json_encode($patch)!
);!
!
$this->isSuccessful($client->getResponse());!
$this->assertEquals(204, $client->getResponse()->getStatusCode());!
}

52. //src/Acme/ApiBundle/Tests/Controller/ApiProductControllerTest.php!
!
public function testDeleteAction()!
{!
$this->loadFixtures(array(!
'AcmeApiBundleTestsFixturesProduct',!
));!
!
$client = static::createClient();!
$client->request('DELETE', '/products/1');!
$this->assertEquals(204, $client->getResponse()->getStatusCode());!
}

53. Documentation

55. //src/Acme/ApiBundle/Controller/ApiProductController.php!
!
use NelmioApiDocBundleAnnotationApiDoc;!
!
/**!
* Returns representation of a given product!
*!
* **Response Format**!
*!
*
{!
*
"product": {!
*
"id": 1,!
*
"name": "Product #1",!
*
"price": 19.9,!
*
"description": "Awesome product"!
*
}!
*
}!
*!
* @ApiDoc(!
*
section="Products",!
*
statusCodes={!
*
200="OK",!
*
404="Not Found"!
*
}!
* )!
*/!
public function getSingleAction(Product $product)!
{!
return array('product' => $product);!
}!

58. Hypermedia?

59. There’s a bundle
for that™

60. willdurand/hateoas-bundle

61. fsc/hateoas-bundle

62. //src/Acme/ApiBundle/Entity/Product.php;!
!
use JMSSerializerAnnotation as Serializer;!
use FSCHateoasBundleAnnotation as Rest;!
use DoctrineORMMapping as ORM;!
!
/**!
* @ORMEntity!
* @ORMTable(name="product")!
* @SerializerExclusionPolicy("all")!
* @RestRelation(!
*
"self", !
*
href = @RestRoute("acme_api_product_get_single", !
*
parameters = { "id" = ".id" })!
* )!
* @RestRelation(!
*
"products", !
*
href = @RestRoute("acme_api_product_get")!
* )!
*/!
class Product!
{!
...!
}

64. application/hal+json

66. GET /orders/523 HTTP/1.1!
Host: example.org!
Accept: application/hal+json!
!
HTTP/1.1 200 OK!
Content-Type: application/hal+json!
!
{!
"_links": {!
"self": { "href": "/orders/523" },!
"invoice": { "href": "/invoices/873" }!
},!
"currency": "USD",!
"total": 10.20!
}

67. “What needs to be done to make the REST
architectural style clear on the notion that
hypertext is a constraint? In other words, if the
engine of application state (and hence the API)
is not being driven by hypertext, then it cannot
be RESTful and cannot be a REST API. Period.
Is there some broken manual somewhere that
needs to be fixed?”
Roy Fielding

68. “Anyway, being pragmatic, sometimes a level
2 well done guarantees a good API…”
Daniel Londero

69. “But don’t call it RESTful. Period.”
Roy Fielding

70. “Ok.”
Daniel Londero

71. THANKS

72. @dlondero