Build REST APIs with Symfony2

Slide 1

Slide 1 text

Build REST APIs with Symfony2 Eduardo Oliveira entering @ github

Slide 2

Slide 2 text

What we are going to talk about? ● HTTP API ● Serialization ● Documentation ● Forms ● Testing ● HTTP Clients ● API Design

Slide 3

Slide 3 text

HTTP API

Slide 4

Slide 4 text

HTTP is a request/response protocol ● Request ○ URI and HTTP method ○ Protocol version ○ Entity (headers and body) ● Response ○ Status code ○ Entity (headers and body)

Slide 5

Slide 5 text

Request POST /speakers HTTP/1.1 Host: symfonyday.pt Content-type: application/json { ... }

Slide 6

Slide 6 text

Response HTTP/1.1 201 Created Location: http://symfonyday.pt/speakers/1 Content-type: application/json { id: 1, name: “...” }

Slide 7

Slide 7 text

Symfony has some tools that helps to build APIs ● Routing ● HTTP Foundation ● Serializer ● Forms

Slide 8

Slide 8 text

Is there something more?

Slide 9

Slide 9 text

FOSRestBundle

Slide 10

Slide 10 text

What does FOSRestBundle do? ● Body decoding ● Multiple output formats ● Exception handling ● Automatic routing ● Content negotiation ● ...

Slide 11

Slide 11 text

Setup

Slide 12

Slide 12 text

Usage

Slide 13

Slide 13 text

Serialization

Slide 14

Slide 14 text

Symfony supports serialization, but there are alternatives

Slide 15

Slide 15 text

JMSSerializerBundle

Slide 16

Slide 16 text

What does JMSSerializerBundle do? ● Integrates JMSSerializer lib into Symfony2 ● Enables (de)serialization of data ● Highly configurable ● Supports versioning and exclusion strategies

Slide 17

Slide 17 text

Usage

Slide 18

Slide 18 text

Result

Slide 19

Slide 19 text

Serializer configuration

Slide 20

Slide 20 text

Result

Slide 21

Slide 21 text

Documentation

Slide 22

Slide 22 text

API documentation is important

Slide 23

Slide 23 text

NelmioApiDocBundle

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Setup

Slide 26

Slide 26 text

Usage

Slide 27

Slide 27 text

Result

Slide 28

Slide 28 text

Forms

Slide 29

Slide 29 text

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”

Slide 30

Slide 30 text

Usage 1/2

Slide 31

Slide 31 text

Usage 2/2

Slide 32

Slide 32 text

Result

Slide 33

Slide 33 text

Testing

Slide 34

Slide 34 text

Some possibilities to test APIs ● Unit testing ○ Test lower layers with unit tests ● Functional testing ○ Test the whole API with Symfony client

Slide 35

Slide 35 text

Functional test

Slide 36

Slide 36 text

HTTP Clients

Slide 37

Slide 37 text

Even if you don’t write APIs, probably you need to consume other APIs

Slide 38

Slide 38 text

Buzz “Buzz is a lightweight PHP 5.3 library for issuing HTTP requests.”

Slide 39

Slide 39 text

Guzzle “Guzzle is a PHP HTTP client and framework for building RESTful web service clients.”

Slide 40

Slide 40 text

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.”

Slide 41

Slide 41 text

Usage 1/2

Slide 42

Slide 42 text

Usage 2/2

Slide 43

Slide 43 text

API Design

Slide 44

Slide 44 text

We also need to know how to properly design REST APIs

Slide 45

Slide 45 text

http://martinfowler.com/articles/richardsonMaturityModel.html

Slide 46

Slide 46 text

Level 0 - tunneling mechanism

Slide 47

Slide 47 text

Level 1 - Resources

Slide 48

Slide 48 text

Level 2 - HTTP Verbs

Slide 49

Slide 49 text

Level 3 - Hypermedia Controls

Slide 50

Slide 50 text

In practice

Slide 51

Slide 51 text

We need two URIs per resource

Slide 52

Slide 52 text

Verbs are bad Nouns are good

Slide 53

Slide 53 text

Concrete naming is good

Slide 54

Slide 54 text

Plural or singular? Plural

Slide 55

Slide 55 text

Collection /speakers Element /speakers/1

Slide 56

Slide 56 text

POST GET PUT DELETE ...

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

Errors HTTP status code Human readable message

Slide 59

Slide 59 text

Format /speakers.json /speakers?_format=json Accept: application/json

Slide 60

Slide 60 text

Format ● URIs identify resources ● URIs are format independent

Slide 61

Slide 61 text

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/ ■ …

Slide 62

Slide 62 text

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 ○ ...

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

Thank you