PHP UK 2015 - Build RESTful APIs easily with Symfony

Build RESTful APIs easily with Symfony Sarah Khalil February 20th,
2015

Who am I? ❖ Trainer ❖ Developer ❖ Enjoying sharer
France

What is REST ?

What is REST? ❖ REpresentational State Transfer ❖ Architecture ❖
Associated to Service Oriented Architecture ❖ Management of resources

Constraints of REST

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

Stateless (2/6) ❖ HTTP ❖ Session on the client side

Cacheable (3/6) ❖ Avoid useless requests

Layered System (4/6) ❖The client requests a resource but it
does not know the system behind.

Uniform interface (5/6) ❖ Each resource has its identiﬁer: URI.
❖ Each resource has its representation. ❖ Auto-descripted message: if it’s JSON, the HTTP Response has a content-type header saying so.

Code on demand (optional) (6/6) ❖ The client could execute
some code coming from the server, to avoid more work on the server side.

HTTP Methods ❖ GET ❖ POST ❖ PUT ❖ DELETE
❖ OPTIONS ❖ HEAD ❖ …

Symfony Full Stack JMSSerializerBundle FOSRestBundle BazingaHateoasBundle Guzzle NelmioApiDocBundle

REQUEST

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

Symfony\Component\HttpFoundation\Request

RESPONSE

HTTP/1.1 200 OK Host: 127.0.0.1:8000 Connection: close X-Powered-By: PHP/5.6.3 Set-Cookie:
PHPSESSID=ecdadm6o2d5v9ei0m181j8gh96; path=/ Cache-Control: no-cacheDate: Wed, 11 Feb 2015 23:42:50 GMT Content-Type: text/html; charset=UTF-8 X-Debug-Token: 32860d X-Debug-Token-Link: /_profiler/32860d <!DOCTYPE html> <html lang="en"> <head>

Symfony\Component\HttpFoundation\Response

RESTful Application Programming Interface

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

Levels http://martinfowler.com

HATEOAS ❖ Hypermedia as the Engine of Application State ❖
Discoverability

How to build all of that?

JMSSerializerBundle Work with resources

Configuration ❖ XML, YAML and Annotation ❖ http://jmsyst.com/libs/serializer/master/reference ❖ Helper
to serialize properties the way you want

Usage 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’) ); } } 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 }

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

Serializer Handler ❖ Special needs ❖ implements JMS\Serializer\Handler\SubscribingHandlerInterface ❖ <tag
name="jms_serializer.subscribing_handler" />

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', ], ]; }

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; }

Event Subscriber ❖ http://jmsyst.com/libs/serializer/master/event_system ❖ serializer.pre_serialize, serializer.post_serialize, serializer.pre_deserialize, serializer.post_deserialize ❖
implements JMS\Serializer\EventDispatcher\EventSubscriberInterface ❖ <tag name="jms_serializer.event_subscriber" type="AppBundle\MyClass" direction="serialization" format="json" method="onPostSerialize"/>

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', ), ); } }

Other features ❖ Serialization Group ❖ Versioning

FOS Rest Bundle Setup your Symfony application

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

Content type negotiation ❖ Request = > Accept ❖ priorities
of media type(s) that your application is ready to get ❖ Response => Content-Type ❖ the media type of the response (html, json, png…)

Content type negotiation ❖ Priorities define the order of media
types as the application prefers # app/config/config.yml fos_rest: format_listener: rules: - { path: '^/', priorities: ['json'], fallback_format: html } ❖ Request: ❖ Accept text/json;q=0.9,*/*;q=0.8,text/html

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

Validation (with the Symfony Validator Component) fos_rest: body_converter: enabled: true
validate: true validation_errors_argument: validationErrors /** * @ParamConverter("post", converter="fos_rest.request_body") */ public function putPostAction(Post $post, ConstraintViolationListInterface $validationErrors) { if (count($validationErrors) > 0) { // Handle validation errors } }

Param Fetcher

/** * @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

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

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

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

Other Features ❖ Automatic generation of routes ❖ Consistency ❖
Versioning ❖ url ❖ mime type ❖ Take a look at the documentation : ❖ http://symfony.com/doc/master/bundles/FOSRestBundle/index.html

BazingaHateoasBundle Unlock the level 3 of the Richardson’s model

HATEOAS ❖ Hypermedia As The Engine Of Application State ❖
Linking resources ❖ Self discovery

HAL ❖ Hypertext Application Language ❖ _links - relations ❖
_embedded - related resource(s) ❖ self ❖ Speciﬁcations: http://stateless.co/hal_speciﬁcation.html

JSON Api ❖ Similar to HAL ❖ meta - meta
info such as pagination… ❖ links - Relation (xToOne, xToMany…) ❖ linked - Resource(s) linked ❖ Speciﬁcations: http://jsonapi.org/format/

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

/** * @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

Result { "id": 1, "_links": { "self": { "href": "http://domaine.name/users/eh1754329986/notiﬁcations/1/"
} } }

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

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

Representation ❖ Use representation to decorate your resource ❖ Hateoas\Representation\PaginatedRepresentation
❖ And many more !

"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" } }

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

Guzzle Communicate between micro services

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

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

Security

Symfony Full Stack JMSSerializerBundle FOSRestBundle BazingaHatoasBundle Guzzle NelmioApiDocBundle

Authentication ❖ Authorization header : Authorization: Bearer <access_token> ❖ https://github.com/poledev/katas/tree/kata-authentication
❖ http://symfony.com/doc/current/cookbook/security/ api_key_authentication.html ❖ Make it stateless

Authorisation ❖ access_control ❖ $this->get(‘security.authorization_checker')->isGranted('ROLE_ADMIN') ❖ {% if is_granted(‘ROLE_ADMIN’) %}
… ❖ Voter ❖ ACL ❖ …

FosHttpCacheBundle keep it in mind

One last thing…

NelmioApiDocBundle Documentation

Many tools, pick what you need!

https://www.ﬂickr.com/photos/jeffclow @Saro0h http://joind.in/talk/view/13387

Some references ❖ Symfony Rest Edition: https://github.com/gimler/symfony-rest-edition ❖ Lukas Kahwe
Smith & William Durand - Build Awesome REST APIs With Symfony2: https://www.youtube.com/watch?v=AcLHvOT5Ekg ❖ REST+JSON API Design - Best Practices for Developers: https://www.youtube.com/watch? v=hdSrT4yjS1g ❖ http://json-ld.org/

PHP UK 2015 - Build RESTful APIs easily with Symfony

PHP UK 2015 - Build RESTful APIs easily with Symfony

More Decks by Sarah KHALIL

Other Decks in Programming

Featured

Transcript