PHP Benelux - Build Restful API easily with Symfony

Let's build a nice REST API with all the recent helper we can find. First of all, we will take some time to see, in theory, what's asked to build a "good" Restfull API.
Then we'll see some code with the usage of :
FOSRestBundle, and save a lot of time;
JMS serializer and its awesome features;
the HATEOAS project, very nice to unlock the third level of the Richardson maturity model;
And finaly, a little bit of guzzle to ease communication between applications (going further with the SOA architecture).
The goal of that talk is to demystify all technologies in the "REST" galaxy.

Transcript

1. Build Restful API easily
   with Symfony Sarah Khalil - January 29th, 2016
   

   View Slide

2. Who am I?
   • Head of
   • Trainer & Developer
   • Enjoying sharer
   Sarah Khalil
   @saro0h
   

   View Slide

3. View Slide

4. What’s the plan?
   

   View Slide

5. What’s the plan?
   Back to basics
   1
   

   View Slide

6. What’s the plan?
   Back to basics
   1
   How to do it?
   2
   

   View Slide

7. What’s the plan?
   Back to basics
   1
   Alternative tools
   3
   How to do it?
   2
   

   View Slide

8. What is REST?
   

   View Slide

9. What is REST?
   • REpresentational State Transfer
   
   • Architecture (not a protocol!)
   
   • Associated to Service Oriented Architecture
   
   • Management of resources
   

   View Slide

10. View Slide

11. View Slide

12. View Slide

13. View Slide

14. The 6 constraints of
    REST
    

    View Slide

15. Client - Server (1/6)
    Separation of concerns
    
    Portability
    

    View Slide

16. Stateless (2/6)
    Based on HTTP
    
    Session has to be held on the client side
    

    View Slide

17. Cacheable (3/6)
    Avoid useless requests
    

    View Slide

18. Layered system (4/6)
    The client doesn’t know the system behind
    

    View Slide

19. Uniform interface (5/6)
    Each resource has its identifier: the URI.
    
    Each resource has its representation.
    
    Auto-descripted message:
    
    for instance, JSON = content-type
    header.
    

    View Slide

20. Code on demand (6/6)
    The client download some code and executes it
    
    The server is not aware of what is happening
    anymore
    optional
    

    View Slide

21. HTTP Methods
    • GET
    
    • POST
    
    • PUT
    
    • PATCH
    • DELETE
    
    • OPTIONS
    
    • CONNECT
    
    • HEAD
    

    View Slide

22. Restful API
    

    View Slide

23. Keep’em in mind
    JSON, XML, HTML…
    
    By developers and for developers
    
    Scalability
    
    Latency
    
    Security
    !
    

    View Slide

24. http://martinfowler.com
    

    View Slide

25. HATEOAS
    Hypermedia as the engine of Application State
    
    Discoverability => Links!
    

    View Slide

26. View Slide

27. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    

    View Slide

28. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    

    View Slide

29. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    

    View Slide

30. Request
    GET /users HTTP/1.1
    User-Agent: curl/7.37.1
    Host: 127.0.0.1:8000
    Accept: */*
    

    View Slide

31. Response
    HTTP/1.1 200 OK
    Host: 127.0.0.1:8000
    Content-Type: text/html; charset=UTF-8
    
    
    
    

    View Slide

32. Symfony\Component\HttpFoundation\Request
    Symfony\Component\HttpFoundation\Response
    

    View Slide

33. HttpKernel
    

    View Slide

34. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    

    View Slide

35. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    Work with resources
    

    View Slide

36. View Slide

37. Json/XML Object
    serialization
    deserialization
    

    View Slide

38. Configuration
    XML, YML and Annotation.
    
    http://jmsyst.com/libs/serializer/master/reference
    
    Helper to serialize properties the way you need.
    

    View Slide

39. class DefaultController
    {
    public function indexAction()
    {
    $obj = new \StdClass();
    $obj->latitude = -33.87087;
    $obj->longitude = 151.225459;
    $data = $this->get(‘jms_serializer’)
    ->serialize($obj, ’json’);
    return new Response(
    $data,
    200,
    array(‘Content-Type’=>’application/json’)
    );
    }
    }
    

    View Slide

40. HTTP/1.1 200 OK
    Host: 127.0.0.1
    X-Powered-By: PHP/5.6.3
    Content-Type: application/json
    {
    "latitude": -33.87087,
    "longitude": 151.225459
    }
    Output
    

    View Slide

41. Exclusion policy
    /**
    * @JMS\ExclusionPolicy("all")
    */
    class Product
    {
    /**
    * @JMS\Expose()
    */
    private $name;
    private $users;
    }
    • Visitor pattern
    
    • Object graph
    
    • Relations (xToMany)
    

    View Slide

42. Serializer handler
    Specific needs
    
    Implements JMS\Serializer\Handler\SubscribingHandlerInterface
    
    

    View Slide

43. View Slide

44. public static function getSubscribingMethods()
    {
    return [
    [
    'direction' =>
    GraphNavigator::DIRECTION_SERIALIZATION,
    'format' => ‘json',
    'type' => ‘AppBundle\MyClass’,
    'method' => ‘serialize',
    ],
    [
    'direction' =>
    GraphNavigator::DIRECTION_DESERIALIZATION,
    'format' => ‘json',
    'type' => ‘AppBundle\MyClass',
    'method' => ‘deserialize',
    ],
    ];
    }
    

    View Slide

45. public function serialize(
    JsonSerializationVisitor $visitor,
    MyClass $object,
    array $type,
    Context $context
    )
    {
    $data = $object->toArray();
    return $data;
    }
    public function deserialize(JsonDeserializationVisitor
    $visitor, $data)
    {
    $object = new AppBundle\MyClass($data);
    return $object;
    }
    

    View Slide

46. Events
    

    View Slide

47. Json/XML Object
    serialization
    deserialization
    serializer.pre_serialize
    serializer.post_serialize
    serializer.pre_deserialize serializer.post_deserialize
    

    View Slide

48. class PostSerializeMediaListener implements EventSubscriberInterface
    {
    public function onPostSerialize(ObjectEvent $event)
    {
    $myObject = $event->getObject();
    $event->getVisitor()->addData('newElementInJson', 'information’);
    }
    public static function getSubscribedEvents()
    {
    return array(
    array(
    'event' => Events::POST_SERIALIZE,
    'format' => ‘json',
    'class' => ‘AppBundle\MyClass',
    'method' => ‘onPostSerialize',
    ),
    );
    }
    }
    

    View Slide

49. Event subscriber
    name="jms_serializer.event_subscriber"
    type="AppBundle\MyClass"
    direction="serialization"
    format="json"
    method="onPostSerialize"
    />
    

    View Slide

50. Other features
    Serialization group
    
    Versionning
    

    View Slide

51. View Slide

52. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    

    View Slide

53. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    Setup your Symfony
    application
    

    View Slide

54. View Slide

55. Controller
    # app/config/config.yml
    fos_rest:
    view:
    view_response_listener: force
    sensio_framework_extra:
    view: { annotations: false }
    /**
    * @View()
    */
    public function getUsersAction()
    {
    …
    return $data;
    }
    

    View Slide

56. Content-Type negociation
    • Request => Accept
    priorities of media-type(s) that your application
    is ready to work with.
    
    • Response => Content-Type
    the media type of the response (html, json,
    png…).
    

    View Slide

57. Content-Type negociation
    Request:
    
    Accept text/json;q=0.9,*/*;q=0.8,text/html
    # app/config/config.yml
    fos_rest:
    format_listener:
    rules:
    - { path: '^/', priorities: ['json'], fallback_format: html }
    weighting
    

    View Slide

58. Request body converter
    Decoder
    
    ParamConverter
    /**
    * @ParamConverter("post", converter="fos_rest.request_body")
    */
    public function updateAction(Post $post)
    {
    }
    # app/config/config.yml
    sensio_framework_extra:
    request: { converters: true }
    fos_rest:
    body_converter:
    enabled: true
    

    View Slide

59. Validation
    

    View Slide

60. Validation (with the Symfony Validator component)
    
    Configuration
    fos_rest:
    body_converter:
    enabled: true
    validate: true
    validation_errors_argument: validationErrors
    

    View Slide

61. Validation (with the Symfony Validator component)
    
    Usage
    /**
    * @ParamConverter("post", converter="fos_rest.request_body")
    */
    public function putPostAction(Post $post, ConstraintViolationListInterface
    $validationErrors)
    {
    if (count($validationErrors) > 0) {
    // Handle validation errors
    }
    }
    

    View Slide

62. Param Fetcher
    

    View Slide

63. /**
    * @QueryParam(
    * name="sort",
    * requirements="(asc|desc)",
    * allowBlank=false,
    * default="asc",
    * description="Sort direction"
    * )
    * @RequestParam(
    * name="firstname",
    * requirements="[a-z]+"
    * )
    * @QueryParam(
    * array=true,
    * name="filters",
    * requirements=@MyComplexConstraint
    * )
    */
    public function getArticlesAction(ParamFetcher $paramFetcher)
    {}
    http://mydomain.com/resources?sort=desc
    In $request->request ($_POST)
    fos_rest.param_fetcher_listener: true
    

    View Slide

64. /**
    * @QueryParam(name="page", requirements="\d+", default="1")
    */
    public function getArticlesAction($page)
    {}
    fos_rest.param_fetcher_listener: force
    

    View Slide

65. Error handling
    

    View Slide

66. Error handling
    
    Option 1
    fos_rest:
    codes:
    'Symfony\Component\Routing\Exception\ResourceNotFoundException': 404
    'Doctrine\ORM\OptimisticLockException': HTTP_CONFLICT
    

    View Slide

67. fos_rest:
    view:
    exception_wrapper_handler: My\Bundle\Handler\MyExceptionWrapperHandler
    1
    Error handling
    
    Option 2
    

    View Slide

68. fos_rest:
    view:
    exception_wrapper_handler: My\Bundle\Handler\MyExceptionWrapperHandler
    1
    implements FOS\RestBundle\ViewExceptionWrapperHandlerInterface
    2
    Error handling
    
    Option 2
    

    View Slide

69. fos_rest:
    view:
    exception_wrapper_handler: My\Bundle\Handler\MyExceptionWrapperHandler
    1
    implements FOS\RestBundle\ViewExceptionWrapperHandlerInterface
    2
    public function wrap($data)
    {
    return new MyExceptionWrapper($data);
    }
    3
    Error handling
    
    Option 2
    

    View Slide

70. fos_rest:
    view:
    exception_wrapper_handler: My\Bundle\Handler\MyExceptionWrapperHandler
    Take example on the FOS\RestBundle\Util\ExceptionWrapper
    1
    implements FOS\RestBundle\ViewExceptionWrapperHandlerInterface
    2
    public function wrap($data)
    {
    return new MyExceptionWrapper($data);
    }
    3
    Error handling
    
    Option 2
    

    View Slide

71. Other features
    • Automatic generation of routes
    
    • Consistency
    
    • Versioning
    
    • url
    
    • mime type
    
    And way more!
    
    http://symfony.com/doc/master/bundles/FOSRestBundle/index.html
    

    View Slide

72. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    

    View Slide

73. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    Unlock the level 3 of the Richardson’s model
    

    View Slide

74. View Slide

75. HAL
    • Hypertext Application Language
    
    • _links - relations
    
    • _embedded - related resource(s)
    
    • self
    • Specifications: http://stateless.co/hal_specification.html
    

    View Slide

76. JSON API
    • Similar to HAL
    
    • meta - meta info such as pagination…
    
    • links - Relations (xToOne - xToMany)
    
    • linked - Resource(s) linked
    
    • Specifications : http://jsonapi.org/format/
    

    View Slide

77. Configuration
    Annotation, XML and YML
    
    Relies on Expression Language (since Symfony 2.4)
    

    View Slide

78. /**
    * @Hateoas\Relation(
    * "self",
    * href = @Hateoas\Route(
    * "get_notification",
    * absolute= true,
    * parameters = {
    * "id" = "expr(object.getId())",
    * "user" = "expr(service(‘security.context’).getToken().getUser().getUuid())"
    * }
    * )
    * )
    */
    class Notification
    Expression Language
    

    View Slide

79. Result
    {
    "id": 1,
    "_links": {
    "self": {
    "href": "http://domaine.name/users/eh1754329986/notifications/1/"
    }
    }
    }
    

    View Slide

80. /**
    * …
    * @Hateoas\Relation(
    * "activity",
    * href = "expr(‘/activity/'~object.getActivity().getId()",
    * embedded = "expr(object.getActivity())",
    * exclusion = @Hateoas\Exclusion(excludeIf = "expr(object.getActivity() === null)")
    * )
    */
    class Notification
    

    View Slide

81. Result
    {
    "id": 1,
    "_embedded": {
    "activity": {
    "id": 3,
    "content": "Activity content",
    "_links": {
    "self": {
    "href": "/activities/3"
    }
    }
    }
    }
    }
    

    View Slide

82. Representation
    Use representation to decorate your resource
    
    Hateoas\Representation\PaginatedRepresentation
    And many more:
    
    https://github.com/willdurand/Hateoas/tree/master/src/Hateoas/Representation
    

    View Slide

83. class CollectionRepresentation
    {
    private $resources;
    public function __construct($resources) {
    $this->resources = $resources;
    }
    public function getResources()
    {
    return $this->resources;
    }
    }
    

    View Slide

84. "resources": {
    {
    "name": « Mercure Los Angeles"
    },
    {
    "name": "Novotel Mexico"
    },
    }
    

    View Slide

85. Representation
    Any representation you need!
    
    A class with the properties you need
    
    Let the serializer do its job
    

    View Slide

86. "page": 1,
    "limit": 10,
    "pages": "100",
    "total": 1000,
    "_links": {
    "self": {
    "href": "http://domain.name/notifcations?page=1&limit=10"
    },
    "first": {
    "href": "http://domain.name/notifcations?page=1&limit=1"
    },
    "last": {
    "href": "http://domain.name/notifcations?page=100&limit=1"
    },
    "next": {
    "href": "http://domain.name/notifcations?page=2&limit=1"
    }
    }
    

    View Slide

87. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    Guzzle
    

    View Slide

88. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    Guzzle
    Communicate between
    microservices
    

    View Slide

89. Frontend
    Service 1
    Service 2
    Service 3
    Service 4
    Private network
    Client
    

    View Slide

90. Guzzle Bundle
    HTTP Client
    
    Request
    
    Response
    
    HTTPS
    
    Error management
    • https://github.com/misd-
    service-development/guzzle-
    bundle
    • https://github.com/csarrazi/
    CsaGuzzleBundle
    

    View Slide

91. View Slide

92. View Slide

93. Security
    

    View Slide

94. Symfony Full Stack
    JMSSerializerBundle
    FOSRestBundle
    BazingaHateoasBundle NelmioApiDocBundle
    

    View Slide

95. Authentication & Authorization
    

    View Slide

96. Authentication & Authorization
    

    View Slide

97. Authentication & Authorization
    

    View Slide

98. Authentication with
    multiple API’s
    

    View Slide

99. Service 1
    Service 2
    Client
    Frontend 2
    Frontend 1
    Service 3
    Service 4
    

    View Slide

100. View Slide

101. Workflow
     1. The user authenticates [him|her]self
     on frontend 1
     2. Do some stuff
     3. Then clicks on a link that brings him/
     her to the frontend 2
     

     View Slide

102. Service 1
     Service 2
     Client
     Frontend 2
     Frontend 1
     Service 3
     Service 4
     GET /admin HTTP/1.1
     User-Agent: curl/7.37.1
     Host: 127.0.0.1:8000
     Accept: */*
     Authorization: Bearer XXXXXX
     

     View Slide

103. Get the token
     In an authenticator, grab the
     Authorization header value
     

     View Slide

104. Get the token
     public function createToken(Request $request, $providerKey)
     {
     $bearer = $request->headers…
     }
     

     View Slide

105. Validate a token / Get a new one…
     

     View Slide

106. View Slide

107. View Slide

108. Authentication
     • Authorization header: Authorization: Bearer
     • https://github.com/poledev/katas/tree/kata-
     authentication
     • http://symfony.com/doc/current/cookbook/security/
     api_key_authentication.html
     • Make it stateless!
     

     View Slide

109. Authorization
     • access_control
     
     • $this->get(‘security.authorization_checker’)->isGranted('ROLE_ADMIN')
     • {% if is_granted(‘ROLE_ADMIN’) %}
     • Voter
     
     • …
     

     View Slide

110. FosHttpCacheBundle
     Keep it mind
     

     View Slide

111. View Slide

112. Ease the usage of your
     API
     

     View Slide

113. Symfony Full Stack
     JMSSerializerBundle
     FOSRestBundle
     BazingaHateoasBundle NelmioApiDocBundle
     

     View Slide

114. Symfony Full Stack
     JMSSerializerBundle
     FOSRestBundle
     BazingaHateoasBundle NelmioApiDocBundle
     Documentation
     

     View Slide

115. View Slide

116. View Slide

117. Alternative to
     FOSRestBundle
     

     View Slide

118. https://api-platform.com/
     

     View Slide

119. View Slide

120. View Slide

121. http://tinyurl.com/sfliveparis
     

     View Slide

122. Thank you!
     @saro0h
     speakerdeck.com/saro0h/
     github.com/saro0h/oauth-github
     Follow me on
     @catlannister
     Come see us at the SensioLabs booth!
     

     View Slide