Build REST APIs with Symfony2

Learn by example how to build a REST API using Symfony2 and third-party libraries. We will talk about routing, forms, serialization, testing, HTTP clients and documentation, we will also focus on how to write elegant and decoupled code.

Transcript

1. Build REST APIs with Symfony2 Eduardo Oliveira entering @ github
2. What we are going to talk about? • HTTP API • Serialization • Documentation • Forms • Testing • HTTP Clients • API Design
3. HTTP API
4. HTTP is a request/response protocol • Request ◦ URI and HTTP method ◦ Protocol version ◦ Entity (headers and body) • Response ◦ Status code ◦ Entity (headers and body)
5. Request POST /speakers HTTP/1.1 Host: symfonyday.pt Content-type: application/json { ... }
6. Response HTTP/1.1 201 Created Location: http://symfonyday.pt/speakers/1 Content-type: application/json { id: 1, name: “...” }
7. Symfony has some tools that helps to build APIs • Routing • HTTP Foundation • Serializer • Forms
8. Is there something more?
9. FOSRestBundle
10. What does FOSRestBundle do? • Body decoding • Multiple output formats • Exception handling • Automatic routing • Content negotiation • ...
11. Setup
12. Usage
13. Serialization
14. Symfony supports serialization, but there are alternatives
15. JMSSerializerBundle
16. What does JMSSerializerBundle do? • Integrates JMSSerializer lib into Symfony2 • Enables (de)serialization of data • Highly configurable • Supports versioning and exclusion strategies
17. Usage
18. Result
19. Serializer configuration
20. Result
21. Documentation
22. API documentation is important
23. NelmioApiDocBundle
24. What does NelmioApiDocBundle do? • Allows to generate documentation for APIs • Introspection to keep docs up to date • Integrates with forms • Integrates with other bundles annotations • Sandbox
25. Setup
26. Usage
27. Result
28. Forms
29. What does Symfony Forms do? • Makes easier to deal with input data • Integrates well with Symfony validator • Together with entities can act as “contract” with the “world”
30. Usage 1/2
31. Usage 2/2
32. Result
33. Testing
34. Some possibilities to test APIs • Unit testing ◦ Test lower layers with unit tests • Functional testing ◦ Test the whole API with Symfony client
35. Functional test
36. HTTP Clients
37. Even if you don’t write APIs, probably you need to consume other APIs
38. Buzz “Buzz is a lightweight PHP 5.3 library for issuing HTTP requests.”
39. Guzzle “Guzzle is a PHP HTTP client and framework for building RESTful web service clients.”
40. Guzzle Service Description “Guzzle allows you to serialize HTTP requests and parse HTTP responses using a DSL called a service descriptions. Service descriptions define web service APIs by documenting each operation … Guzzle's service descriptions are heavily inspired by Swagger.”
41. Usage 1/2
42. Usage 2/2
43. API Design
44. We also need to know how to properly design REST APIs
45. http://martinfowler.com/articles/richardsonMaturityModel.html
46. Level 0 - tunneling mechanism
47. Level 1 - Resources
48. Level 2 - HTTP Verbs
49. Level 3 - Hypermedia Controls
50. In practice
51. We need two URIs per resource
52. Verbs are bad Nouns are good
53. Concrete naming is good
54. Plural or singular? Plural
55. Collection /speakers Element /speakers/1
56. POST GET PUT DELETE ...
57. Resource POST (create) GET (read) PUT (update) DELETE (delete) /speakers new speaker list speaker bulk update delete all speakers /speakers/1 error show speaker replace speaker delete speaker
58. Errors HTTP status code Human readable message
59. Format /speakers.json /speakers?_format=json Accept: application/json
60. Format • URIs identify resources • URIs are format independent
61. Additional Resources 1/2 • Blogs ◦ REST APIs with Symfony2: The Right Way ▪ http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2- the-right-way/ ◦ Symfony2 REST API: the best way ▪ http://welcometothebundle.com/symfony2-rest-api-the- best-2013-way/ ▪ …
62. Additional Resources 2/3 • Presentations ◦ https://speakerdeck.com/gordalina/rest-apis-made-easy-with- symfony2 ◦ https://speakerdeck.com/willdurand/build-awesome-rest-apis- with-symfony2 ◦ ...
63. Additional Resources 3/3 • Bundles/libs ◦ https://github.com/FriendsOfSymfony/FOSRestBundle ◦ https://github.com/nelmio/NelmioApiDocBundle ◦ https://github.com/willdurand/BazingaHateoasBundle ◦ https://github.com/willdurand/Negotiation ◦ https://github.com/guzzle/guzzle
64. Thank you