Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Build REST APIs with Symfony2

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.

2b4bf59f2c087901149b2075c8c19006?s=128

Eduardo Oliveira

March 08, 2014
Tweet

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