Welcome

Michaël Villeneuve

CTO @ ctrlweb

1 year

8 meetups in 2016

1 every ~6 weeks

- Docker et Symfony (16/11/2015)
- Symfony 3.0 (25/01/2016)

- TDD & BDD with Symfony - Steven Rosato (02/04/2016)
- Create an API with FOSRestBundle (Today!)
- Create a CMS with SonataAdminBundle
- How to optimise Doctrine
- Symfony caching system 
- SyliusBundle

Before we start...

- Anyone looking / offering for a job ?

- Summer break with Yuldev (06/08/2016) 

- Sponsors

Before we start...

Subscribe :)

Today

• RESTful principles
• REST Standards

API?

RESTful principles

• Resource: A single instance of an object. For example, an animal.
• Collection: A collection of homogeneous objects. For example, animals.
• HTTP: A protocol for communicating over a network.
• Consumer: A client computer application capable of making HTTP requests.
• Server: An HTTP server/application accessible from a Consumer over a network.
• Endpoint: An API URL on a Server which represents either a Resource or an entire Collection.

RESTful principles

• GET (SELECT) - Fetch a resource from the server
• POST (CREATE) - Create a resource from the server
• PUT (UPDATE) - Update a resource from the server providing the entire resource
• PATCH (UPDATE) - Update a resource from the server providing only the attributes                                             that have been changed
• DELETE (DELETE) - I'll let you guess :)
• HEAD - Wont be covered today - retreive a metadata about a resource
• OPTIONS - Wont be covered today – Returns what methods are allowed with a                                      resource, required by CORS (Cross Origin Resource Sharing), useful for                                  the consumer

Versioning

1. Your application will change
2. It is your responsability to never break backward compatibility. (symfony.com/bc)

WHY?

Versioning

1. Using an URL segment : https://mydomain.com/api/{version}/{resource}

2. GET /foo HTTP/1.1
   Host: api.example.org
   Version: 1.2

HOW?

Standards

Endpoints

Status code cheat sheet

Authorization

vs

Authentication

Reference

Consumer-Centric API Design

Step 1: Setting up the bundle

1. Install the bundle
    
2. Enable the bundle

$ composer require friendsofsymfony/rest-bundle
$ composer require jms/serializer-bundle

// app/AppKernel.php
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new FOS\RestBundle\FOSRestBundle(),
            new JMS\SerializerBundle\JMSSerializerBundle(),
        );

        // ...
    }
}

Automatic routing 

  php bin/console debug:router --env=prod
       
  get_products               GET      ANY      ANY    /products.{_format}                
  get_product                GET      ANY      ANY    /products/{slug}.{_format}         

Tools

Postman

Versioning

# app/config.php
fos_rest:
    versioning: true

# app/routing.php
products:
    type:     rest
    prefix: /api/{version}
    resource: ProductBundle\Controller\ProductsController


# ProductBundle/Controller/ProductsController
use FOS\RestBundle\Controller\Annotations\Version;

/**
 *
 * @RouteResource("Product")
 * @Version({"v1", "v2"})
 */
class ProductsController extends FOSRestController

* Only available since FOSRESTBundle 2.x>

# app/config.php
jms_serializer:
    metadata:
        auto_detection: true
        directories:
            UserBundle:
                path: "@UserBundle/Resources/config/serializer"

# UserBundle\Resources\config\serializer\Entity.User.yml
UserBundle\Entity\User:
    exclusion_policy: ALL
    properties:
        username:
            expose: true

    public function getUserAction($slug)
    {} // "get_user"             [GET] /users/{slug}

    public function editUserAction($slug)
    {} // "edit_user"            [GET] /users/{slug}/edit

    public function putUserAction($slug)
    {} // "put_user"             [PUT] /users/{slug}

    public function patchUserAction($slug)
    {} // "patch_user"           [PATCH] /users/{slug}

    public function getUserCommentsAction($slug)
    {} // "get_user_comments"    [GET] /users/{slug}/comments

    public function newUserCommentsAction($slug)
    {} // "new_user_comments"    [GET] /users/{slug}/comments/new

    public function postUserCommentsAction($slug)
    {} // "post_user_comments"   [POST] /users/{slug}/comments

Documentation

Documentation

Security

• Rate limit
• Authorization / Authentication
• FOSOAuthServerBundle

Testing

• Behat
• PHPSpec
• FactoryMuffin

Here's a simple comprehensive tutorial