Share
Embed
REST dans le monde Symfony (PHPTour)
Voici un tour d'horizon des outils disponibles pour créer des APIs REST robustes en PHP et plus précisément avec le framework Symfony2. Les différentes couches en jeu seront passées en revue, que ce soit le routing, la sérialisation, le versioning, les tests, mais également la documentation de vos APIs. Globalement, cette présentation fera l'état des lieux de REST dans le monde Symfony.
Online slides: http://friendsofsymfony.github.io/slides/rest-dans-le-monde-symfony.html
Sources: https://github.com/FriendsOfSymfony/friendsofsymfony.github.com
William Durand
June 23, 2014
Transcript
55 slides
-
REpresentational State Transfer REST is the underlying architectural principle of
the web. It is formalized as a set of constraints, described in Roy Fielding'ʹs dissertation. -
Level 0 -‐‑ The Swamp of POX HTTP as a
tunneling mechanism RPC style system (SOAP, XML-‐‑RPC) -
Level 2 -‐‑ HTTP Verbs Client uses specific HTTP
verbs Server uses HTTP status codes -
HTTP Verbs Method Safe? Idempotent? GET yes yes HEAD yes
yes POST no no PUT no yes DELETE no yes (*) ... no no Safe : means cacheable. Idempotent : result independent on the number of executions. -
HTTP Status Codes Code range Description Example 1xx Information 100
-‐‑ Continue 2xx Successful 201 -‐‑ Created 3xx Redirection 301 -‐‑ Moved Permanently 4xx Client Error 404 -‐‑ Not Found 5xx Server Error 501 -‐‑ Not Implemented -
Level 3 -‐‑ Hypermedia Controls Service discovery via link relations
Hypermedia formats (ATOM, HAL, JSON-‐‑LD, etc.) -
Content Type Negotiation Content Type Negotiation is the principle of
finding appropriate response formats based on client requirements. No standardized algorithm available Apache algorithm is documented though Also covers encoding (Accept-Encoding) and language (Accept-Language) negotiation mod_negotiation -
Example Accept: application/json, application/xml;q=0.9, text/html;q=0.8, text/*;q=0.7, */*;q=0.5 Priority Description q=1.0
application/json q=0.9 application/xml q=0.8 text/html q=0.7 text/* (ie. any text) q=0.5 */* (ie. any media type) -
HATEOAS Hypermedia As The Engine Of Application State. It means
that hypermedia should be used to find your way through the API. It is all about state transitions. Your application is just a big state machine. <?xml version="1.0" encoding="UTF-8"?> <collection page="1" limit="10" pages="1"> <user id="123"></user> <user id="456"></user> <link rel="self" href="/api/users?page=1&limit=10" /> <link rel="first" href="/api/users?page=1&limit=10" /> <link rel="last" href="/api/users?page=1&limit=10" /> </collection> -
In A Nutshell Integrates the library with Symfony2 Enables
(de) serialization of object graphs Implements visitor pattern to enable flexibility Fully leverage native JSON and XML Custom exclusion strategies to determine what to serialize JMS Serializer -
Usage use JMS\SerializerBundle\Annotation as Serializer; /** @Serializer\XmlRoot("response") */ class MyResponse
{ /** * @Serializer\XmlList(inline=true, entry="article") */ protected $articles; /** * @Serializer\XmlAttribute() */ protected $page; public function __construct(Collection $articles, $page) { $this->articles = $articles; $this->page = $page; } } -
In A Nutshell Toolbox of services and listeners to build
RESTful APIs Generate HTML, XML, JSON from a single action Automatic generation of routes from actions GET parameter parsing and validation Integration with Symfony2 serializer and JMS Serializer Integration with SensioFrameworkExtraBundle Accept header negotiation (thx to the lib) Request body decoding Negotiation -
Usage class RestController { /** * Get the list of
articles * route name: liip_hello_rest_get_articles * pattern: /liip/hello/rest/articles.{_format} * http method requirement: GET * * @View() * @QueryParam(name="page", requirements="\d+", default="1") */ public function getArticlesAction($page) { $articles = array('bim', 'bam', 'bingo'); return new \Acme\MyBundle\MyResponse($articles, $page); } } -
Content Type Negotiation fos_rest: format_listener: rules: - path: ^/ priorities:
[ html, json, xml ] fallback_format: ~ prefer_extension: true Accept: application/json, application/xml;q=0.9, text/html;q=0.8, text/*;q=0.7, */*;q=0.5 -
Message Decoding Listener to decode message body from XML, JSON,
etc. into the request parameter bag Integration with SensioFrameworkExtraBundle converters to turn parameters to objects GET parameter validation and normalization -
Allowed Methods Listener Examines all available routes to determine what
HTTP methods are available for the request URI Automatically sets an according Allow header in the response fos_rest: allowed_methods_listener: true HTTP/1.1 200 OK Allow: GET, POST -
MIME Type Listener Register MIME types that Symfony2'ʹs Request class
does not support by default fos_rest: view: mime_types: json: ['application/json', 'application/vnd.example-com.foo+json'] rss: 'application/rss+xml' jpg: 'image/jpeg' png: 'image/png' jsonp_handler: ~ p JSONP callback validation thanks to the library JsonpCallbackValidator -
Error Handling Return correct HTTP status code Determine for which
exception to expose the exception message Automatically extract errors from a Form instance fos_rest: exception: codes: 'Symfony\Component\Routing\Exception\ResourceNotFoundException': 404 'Doctrine\ORM\OptimisticLockException': HTTP_CONFLICT messages: 'Symfony\Component\Routing\Exception\ResourceNotFoundException': true -
In A Nutshell Integrates the library with Symfony2 Leverages
the JMS Serializer library Relies on the Symfony2 ExpressionLanguage component Supports JSON and XML Allows to configure links and embedded resources in XML, YAML, PHP, or Annotations Dynamic relations (relation providers) Exclusion strategies Hateoas -
Usage use JMS\Serializer\Annotation as Serializer; use Hateoas\Configuration\Annotation as Hateoas; /**
* @Serializer\XmlRoot("user") * * @Hateoas\Relation("self", href = "expr('/api/users/' ~ object.getId())") */ class User { /** @Serializer\XmlAttribute */ private $id; private $firstName; private $lastName; public function getId() {} } -
JSON $hateoas = HateoasBuilder::create()->build(); $json = $hateoas->serialize(new User(123, 'John', 'Doe'),
'json'); { "id": 123, "first_name": "John", "last_name": "Doe", "_links": { "self": { "href": "/api/users/123" } } } -
XML $hateoas = HateoasBuilder::create()->build(); $xml = $hateoas->serialize(new User(123, 'John', 'Doe'),
'xml'); <user id="123"> <first_name> </first_name> <last_name> </last_name> <link rel="self" href="/api/users/123"/> </user> <![CDATA[John]]> <![CDATA[Doe]]> -
RFC 6570: URI Template A compact sequence of characters for
describing a range of URIs through variable expansion. URIs URI Template http://example.com/~fred/ http://example.com/~ {username}/ http://example.com/~mark/ -
Usage demo_route: pattern: /demo/{page} $templateLink = $this ->get('hautelook.router.template') ->generate('demo_route', array(
'page' => '{page}', 'sort' => '{sort}', 'filter' => array('{filter}'), )); /demo/{page}?{&sort}{&filter%5B%5D*} p Standalone library: TemplatedUriRouter -
In A Nutshell Generates documentation for your REST APIs Gathers
information from PHPDoc Supports FOSRestBundle, SensioFrameworkExtraBundle, JMSSerializerBundle and JMSSecurityExtraBundle annotations Supports your own annotations Allows to add your own parsers Sandbox (Killer Feature ♥) -
Usage /** * List all notes. * * @ApiDoc( *
resource = true, * statusCodes = { 200 = "Returned when successful" } * ) * @QueryParam( * name="offset", requirements="\d+", nullable=true, * description="Offset from which to start listing notes." * ) * @QueryParam( * name="limit", requirements="\d+", default="5", * description="How many notes to return." * ) */ public function getNotesAction() {} -
In A Nutshell Response listener to add Cache-Control headers Listener
matches the Request path/host/method/attributes Varnish helper class to assist in purging/banning content Listener to combine reverse proxies with Symfony2 security Listener to move flash messages into a cookie -
What Is OAuth? OAuth is an open protocol to allow
secure authorization in a simple and standard method from web, mobile and desktop applications. It is an authorization framework that enables a third-‐‑party application to obtain limited access to an HTTP service. http://edu.williamdurand.fr/security-‐‑slides/#slide85 -
FOSOAuthServerBundle Server-‐‑side implementation of OAuth2 Supports Doctrine ORM|ODM, Propel Highly
configurable Thank you for helping us! Alan Gabriel Bem for OAuth1.0a. BazingaOAuthServerBundle -
Further Reading http://www.ietf.org/rfc/rfc2616.txt http://martinfowler.com/articles/richardsonMaturityModel.html http://roy.gbiv.com/untangled/2008/rest-‐‑apis-‐‑must-‐‑be-‐‑hypertext-‐‑driven http://www.slideshare.net/Wombert/designing-‐‑http-‐‑interfaces-‐‑and-‐‑restful-‐‑web-‐‑services-‐‑dpc2012-‐‑20120608 http://williamdurand.fr/2012/08/02/rest-‐‑apis-‐‑with-‐‑symfony2-‐‑the-‐‑right-‐‑way/ http://www.mnot.net/blog/2012/12/04/api-‐‑evolution http://knpuniversity.com/blog/what-‐‑the-‐‑rest http://knpuniversity.com/blog/rest-‐‑revisited
http://timelessrepo.com/haters-‐‑gonna-‐‑hateoas http://blog.liip.ch/archive/2013/10/28/resting-‐‑with-‐‑symfony2.html http://williamdurand.fr/2014/02/14/please-‐‑do-‐‑not-‐‑patch-‐‑like-‐‑an-‐‑idiot/