About REST & Symfony

ABOUT REST &
SYMFONY
Maxence POUTORD
| | @_maxpou (https://twitter.com/_maxpou)  maxpou.fr (http://www.maxpou.fr/) 
maxence.poutord@gmail.com (mailto:maxence.poutord@gmail.com)

1 . 1
1 . 2
REVEALJS TIPS
ESC: slide overview
ALT + click: zoom
B: blackout
S: speaker notes
Print (then ctrl + p) (?print-pdf)

2 . 1
ABOUT ME
GET /speaker/maxpou HTTP/1.1
{
"name": "Maxence POUTORD",
"skills": ["Symfony2", "API", "NodeJS", "Software quality"],
"hobbies": ["motorbike", "cinema (Danish)", "cooking"],
"job": {
"job": "web consultant",
"company": "Conserto"
}
"_links": {
"self": { "href": "maxpou.fr/slides/slides/about-rest/" },
"blog": { "href": "maxpou.fr" },
"Twitter": { "href": "twitter.com/_maxpou" },
"mail": { "href": "maxence.poutord@gmail.com" }
}
}

REST:
REPRESENTATIONAL STATE TRANSFER

3 . 1
3 . 2
REST IN A NUTSHELL
So ware architectural style for World Wide Web apps
Introduced by Roy Thomas Fielding in 2000
PhD dissertation: Architectural Styles and the Design of Network-b
So ware Architectures
(http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_s
 REST is NOT a protocol!

3 . 3
REST CONSTRAINTS
Client–server: clients and servers are separated
Stateless: each request can be treated independently
Cache: client can cache response
Uniform Interface: client and server share a uniform
interface
Layered system: scalability (load balancing), security
(firewalls)
*Code-On-Demand (a.k.a. COD): client request code (flash,
java applet, js) from server and execute it!
* COD is the only one optional constraint in REST (because it's
reduce visibility & not every API need it)

3 . 4
RESOURCES AND REPRESENTATIONS
Resource: can be anything. Representation: Describe a
resource state
beer:
id: 42
shortName: Kwak
name: Pauwel Kwak
alcoholDegree: 8.4
color: amber
since: 1980
brewery: Bosteels Brewery
<beer id="42">
<short-name>Kwak</short-name>
<name>Pauwel Kwak</name>
<name>8,4</name>
<brewery id="51">
<name>Bosteels Brewery</name>
</brewery>
</beer>

4 . 14 . 2
REST AND THE RICHARDSON
MATURITY MODEL (RMM)
martinfowler.com
(http://martinfowler.com/articles/richardsonMaturityModel.html)

5
LEVEL 0: SWAMP OF POX
HTTP tunnel request
Only POST/GET method
One entry point
/beer
/beer?action=list
/beer?action=get&id=3
/beer?action=delete&id=3
Example: SOAP and XML-RPC

6 . 1
LEVEL 1: RESOURCES
Identification of resources
1 URI = 1 resource
Example:
/breweries/51
/breweries/51/beers/42

6 . 2
ROUTE PATTERN (1/2):
/BEER/1 OR /BEERS/1?
Both of them are REST!
/hellomynameismaxenceandherearemybeers/1 works too!
But, plural noun should be used for collection names

6 . 3
ROUTE PATTERN (2/2): ADVICES
Avoid:
/beers/42/
/beers/42.json
/beers//limit/26
/ugly_name/42
/UglyName/42
Instead, prefer:
/ugly-name/42
/beers?color=blond
/beers?offset=12&limit=5&exclude=2,3&sort=-alcohol
"Cool URIs don't change"
— W3C

7 . 1
LEVEL 2: HTTP VERBS
Client use HTTP verbs
Example: GET, POST, PUT et DELETE...
Server use HTTP codes.
Represent a result of an action
Example: 200, 201, 403, 404, 500...

7 . 2
FOCUS: HTTP VERBS
Method Safe? Idempotent?
GET Yes Yes
HEAD Yes Yes
POST No No
PUT No Yes
PATCH No No
DELETE No Yes
Safe = cacheable
Idempotent = result independent on the number of executions

7 . 3
FOCUS: HTTP CODES 101
1XX Information
2XX Success
3XX Redirection
4XX Client Error
5XX Server Error

7 . 4
HTTP STATUS: THE BARE MINIMUM
200: OK
201: Created
204: No Content
206: Partial Content
301: Moved Permanently
400: Bad request
404: Not Found
500: Internal Server Error
List of HTTP status codes (Wikipedia)
(https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)

7 . 5
STILL LOST?
HTTP Status Codes Map (By Restlet) (http://restlet.com/http-
status-codes-map)

8 . 1
AM I RESTFUL IF I'M ONLY LEVEL 2
COMPLIANT?

8 . 2
WHY?
GET /beers
<beers>
<beer id="42">
<name>Pauwel Kwak</name>
<alcohol>8.4</alcohol>
</beer>
<beer id="101">
<name>Tripel Karmeliet</name>
<alcohol>8.4</alcohol>
</beer>
</beers>
 How can I interact with my Kwak?

8 . 3
WHAT DID ROY FIELDING SAID
If the engine of application state (and hence the API) is not being
driven by hypertext, then it cannot be RESTful and cannot be a
REST API. Period. [...]
Please try to adhere to them or choose some other buzzword for
your API.
Roy T. FIELDING - REST APIs must be hypertext-driven
(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hypertext-driven)

9 . 1
LEVEL 3: HYPERMEDIA CONTROLS
(HATEOAS)
Hypertext As The Engine Of The Application State
Resources are self-describing/self-documenting
(discoverability)
Expose state and behavior: "the application state is
controlled and stored by the user agent"
Use links to describe HOW the service is used, and media
types to describe WHAT is expect

9 . 2
WITHOUT HATEOAS
<consumptions>
<consumption>
<beer id="42">
<name>Kwak</name>
</beer>
<formats>
<format qty="4">Pint</format>
</formats>
</consumption>
<consumption>
<beer id="101">
</beer>
<formats>
<format qty="1">Half</format>
<format qty="0">Pint</format>
</formats>
</consumption>
</consumptions>

9 . 3
HATEOAS
<consumptions>
<consumption>
<beer id="42">
<name>Kwak</name>
<link rel="_self" href="/beers/42">
</beer>
<formats>
<format qty="8">
<name>Half</name>
<link rel="serve" href="/serve/beer/42?format=half">
</format>
</formats>
</consumption>
<consumption>
<beer id="101">
<link rel="_self" href="/beers/101">
</beer>
<formats>

9 . 4
CONTENT NEGOTIATION
Before:
GET /fr/breweries/51.json
GET /en/breweries/51.xml
...
A er:
GET /breweries/51
Accept: application/json, application/xml;q=0.9, text/html;q=0.8,
text/*;q=0.7, */*;q=0.5
Accept-Language: fr, en;q=0.8, de;q=0.7

10 . 2
WELL... MAYBE NOT!
JSON is not a hypermedia format

10 . 3
HAL+JSON example:
HAL (HYPERTEXT APPLICATION
LANGUAGE)
{
"_links": {
"self": { "href": "/beers?offset=1&limit=10" },
"next": { "href": "/beers?offset=11&limit=10" },
"ea:find": {
"href": "/beers{?id}",
"templated": true
}
}
}

10 . 4
JSON-LD
{
"@context": "http://schema.org",
"@type": "Brewery",
"name": "Bosteels Brewery",
"url": "http://bestbelgianspecialbeers.be",
"address": {
"@type": "PostalAddress",
"streetAddress": "Kerkstraat 96",
"addressLocality": "9255 Buggenhout",
"addressRegion": "Belgium"
}
}

10 . 5
10 . 6
Which hypermedia type?
OTHERS
Hydra + JSON-LD
SIREN
...

sookocheﬀ.com/post/api/on-choosing-a-hypermedia-format/
(http://sookocheﬀ.com/post/api/on-choosing-a-hypermedia-
format/)

11 . 1
REST = CRUD?
POST /contact
# mail body

11 . 2
VERSIONING
HTTP/1.1 200 OK
Content-Type: application/json; version=2
Location: /breweries/51
Deprecated call?
HTTP/1.1 406 NOT ACCEPTABLE
Content-Type: application/json
["application/json; version=1", "application/json; version=2", "application/xml; ver

11 . 5
SECURITY
Authorization: OAuth
Authentication: OpenID
Both: OpenID Connect
Transport: TLS
OWASP REST Security Cheat Sheet
(https://www.owasp.org/index.php/REST_Security_Cheat_Shee

DEVELOPER EXPERIENCE
3:30:3 RULE (BY ORI PEKELMAN)
3 sec: WHAT
30 sec: WHERE
3 min: HOW

12 . 2
RAML 1.0
/beers:
/{beerId}:
get:
description: Retrieve a specific beer
responses:
200:
body:
application/json:
example: |
{
"data": {
"id": "42",
"title": "Kwak",
"description": null,
"alcohol": 8.4
"_link": {
"_self": "http:/api.app.com/beers/42"
}
},

12 . 3
SWAGGER
Web API doc body format: FormData request format: json
GET /api/beers Bet all Beers entities
GET /api/beers/{id} Bet a Beer entity
GET /api/breweries Get all Breweries entities
POST /api/breweries Add a Brewery
GET /api/breweries/{id} Get a Brewery entity
PUT /api/breweries/{id} Update an existing Brewery (cannot create here, sorry)
Documentation auto-generated on Mon, 15 Feb 16 10:04:16 +0100

13 . 2
JMS SERIALIZER
In a nutshell:
(De-)serialize data of any complexity
Support XML, JSON, and YAML
Doctrine support
Custom exclusion strategies
 schmittjoh/serializer
(https://github.com/schmittjoh/serializer)

13 . 3
PROBLEM WITH MAPPING ENTITIES

13 . 4
DESIGN PATTERN: DATA TRANSFER
OBJECT
BeerDTO
name: String
brewery: StringBeers
name: String
Beers
Assembler
Brewery
name: String
location: String
alcohol: ﬂoat
Data Transfer Object - Martin Fowler
(http://martinfowler.com/eaaCatalog/dataTransferObject.html)

13 . 5
FOSRESTBUNDLE
Toolbox
Automatic route generation
Content negotiation
Exceptions
Support (Symfony) Forms
API versioning
 FriendsOfSymfony/FOSRestBundle
(https://github.com/FriendsOfSymfony/FOSRestBundle)

13 . 6
FOSRESTBUNDLE: EXAMPLE
/**
* Get all Breweries entities
*
* @QueryParam(name="offset", requirements="d+", nullable=true,
* description="Offset from which to start listing breweries.")
* @QueryParam(name="limit", requirements="d+", nullable=true,
* description="How many breweries to return.")
*/
public function getBreweriesAction(ParamFetcher $paramFetcher)
{
$offset = $paramFetcher->get('offset');
$limit = $paramFetcher->get('limit');
$em = $this->getDoctrine()->getManager();
$breweries = $em ->getRepository('MaxpouBeerBundle:Brewery')
->findBy([], ['name' => 'ASC'], $limit, $offset);
return $breweries;
}

13 . 7
BAZINGAHATEOASBUNDLE
implementing representations for HATEOAS REST web
service
Exclusion strategies
Allows to configure links and embedded resources in XML,
YAML, PHP, or Annotations
 willdurand/BazingaHateoasBundle
(https://github.com/willdurand/BazingaHateoasBundle)

13 . 8
BAZINGAHATEOASBUNDLE: CODE
use HateoasConfigurationAnnotation as Hateoas;
/**
* BreweryDTO
* No business logic here
* @HateoasRelation("self", href = @HateoasRoute("api_get_brewerie", parameters =
*/
class BreweryDTO
{
private $id;
private $name;
/** @return UUID object id **/
public function getId()
{
return $this->id;
}
}

13 . 9
BAZINGAHATEOASBUNDLE: RESULT
GET breweries/6b9f3cfa-cc2c-11e5-8adf-2c4138ad20fa
{
"id": "6b9f3cfa-cc2c-11e5-8adf-2c4138ad20fa",
"name": "Bosteels brewery",
"_links": {
"self": {
"href": "/beerApp/web/app_dev.php/api/breweries/6b9f3cfa-cc2c-11e5-8adf-2c41
}
}
}

13 . 10
NELMIOAPIDOCBUNDLE
Generate a decent documentation
Swagger format
Support PHPDoc, JMS Serializer, FOSRestBundle, (SF) Forms
Export documentation (JSON, HTML, markdown)
Multiple documentation
Sandbox !

13 . 11
NELMIOAPIDOCBUNDLE: EXAMPLE
<?php
use NelmioApiDocBundleAnnotationApiDoc;
/**
* Get all Breweries entities
*
* @ApiDoc(
* statusCodes={
* 200="Returned when successful"
* })
* @QueryParam(name="offset", requirements="d+", nullable=true,
* description="Offset from which to start listing breweries.")
* @QueryParam(name="limit", requirements="d+", nullable=true,
* description="How many breweries to return.")
*/
public function getBreweriesAction(ParamFetcher $paramFetcher)
{
//...
}

13 . 12
SEE ALSO
Bundles:
friendsofsymfony/http-cache (Reverses proxies like varnish)
nelmio/cors-bundle (CORS)
hautelook/TemplatedUriRouter (RFC-6570)
dunglas/DunglasApiBundle (JSON-LD)
Examples:
gimler/symfony-rest-edition
liip/LiipHelloBundle

CONCLUSION
"REST isn’t what you think it is, and that’s OK"

15 . 1
15 . 2
By Leonard Richardson, Mike Amundsen, Sam Ruby

FURTHER READING
martinfowler.com/articles/richardsonMaturityModel.html
(http://martinfowler.com/articles/richardsonMaturityModel.htm
williamdurand.fr (http://williamdurand.fr)
RFC 2616 (hwww.ietf.org/rfc/rfc2616.txt)
https://groups.google.com/forum/#!forum/resting-with-symfony
(https://groups.google.com/forum/#!forum/resting-with-
symfony)

15 . 4
16 . 1
THANK YOU
QUESTIONS?

About REST & Symfony

More Related Content

Similar to About REST & Symfony (20)

Recently uploaded (20)

About REST & Symfony