Introducing API Platform

Kévin Dunglas

@dunglas

Founder of Les-Tilleuls.coop
Symfony core-team
API Platform creator
Teacher at USTL (Lille 1)

Les-Tilleuls.coop

@coopTilleuls

Self-managed IT company (SCOP)
Expertise and dev
Symfony, Angular, Node, Go...
We are hiring!

The web has changed!

More and more Javascript webapps - and Google crawls them
Users spend more time on mobile than on desktops: responsive websites and mobile apps required
JSON-LD, Schema.org, Hydra: Linked Data and the semantic web start to be massively used

{
    "@context": "/contexts/Person",
    "@id": "/people",
    "@type": "hydra:PagedCollection",
    "hydra:totalItems": 1,
    "hydra:itemsPerPage": 30,
    "hydra:firstPage": "/people",
    "hydra:lastPage": "/people",
    "hydra:member": [
        {
        "@id": "/people/1",
        "@type": "http://schema.org/Person",
        "gender": "male",
        "name": "Dunglas",
        "url": "https://dunglas.fr"
        }
    ]
}

Step 1

Pick types and properties you need from Schema.org:

namespaces:
  entity: AppBundle\Entity
types:
  Person:
    parent: false
    properties:
      name: ~
      birthDate: ~
      gender: ~

There is no step 3

<?php

namespace AppBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Dunglas\ApiBundle\Annotation\Iri;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * A person (alive, dead, undead, or fictional).
 *
 * @see http://schema.org/Person Documentation on Schema.org
 *
 * @ORM\Entity
 * @Iri("http://schema.org/Person")
 */
class Person
{
    /**
     * @var integer
     * @ORM\Column(type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    private $id;
    /**
     * @var string The name of the item.
     *
     * @ORM\Column(nullable=true)
     * @Assert\Type(type="string")
     * @Iri("https://schema.org/name")
     */
    private $name;
    /**
     * @var \DateTime Date of birth.
     * @Assert\Date
     * @ORM\Column(type="date", nullable=true)
     * @Iri("http://schema.org/birthDate")
     */
    private $birthDate;
    /**
     * @var string Gender of the person.
     * @Assert\Type(type="string")
     * @ORM\Column(nullable=true)
     * @Iri("http://schema.org/gender")
     */
    private $gender;

    /**
     * Sets id.
     *
     * @param  integer $id
     * @return $this
     */
    public function setId($id)
    {
        $this->id = $id;

        return $this;
    }

    /**
     * Sets name.
     *
     * @param string $name
     *
     * @return $this
     */
    public function setName($name)
    {
        $this->name = $name;

        return $this;
    }

    /**
     * Gets name.
     *
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * Gets id.
     *
     * @return integer
     */
    public function getId()
    {
        return $this->id;
    }

    /**
     * Sets birthDate.
     *
     * @param  \DateTime $birthDate
     * @return $this
     */
    public function setBirthDate(\DateTime $birthDate)
    {
        $this->birthDate = $birthDate;

        return $this;
    }

    /**
     * Gets birthDate.
     *
     * @return \DateTime
     */
    public function getBirthDate()
    {
        return $this->birthDate;
    }

    /**
     * Sets gender.
     *
     * @param  string $gender
     * @return $this
     */
    public function setGender($gender)
    {
        $this->gender = $gender;

        return $this;
    }

    /**
     * Gets gender.
     *
     * @return string
     */
    public function getGender()
    {
        return $this->gender;
    }
}

Define resources to expose


# app/config/services.yml

services:
    person_resource:
        parent:    "api.resource"
        arguments: [ "AppBundle\Entity\Person" ]
        tags:      [ { name: "api.resource" } ]

GET /people

{
    "@context": "/contexts/Person",
    "@id": "/people",
    "@type": "hydra:PagedCollection",
    "hydra:totalItems": 1,
    "hydra:itemsPerPage": 30,
    "hydra:firstPage": "/people",
    "hydra:lastPage": "/people",
    "hydra:member": [
        {
        "@id": "/people/1",
        "@type": "http://schema.org/Person",
        "name": "Dunglas",
        "gender": "male",
        "birthDate": "1988-21-01T00:00:00+01:00"
        }
    ]
}

A collection by API Platform (JSON-LD + Hydra output)

# src/app/config.yml

nelmio_cors:
    defaults:
        allow_origin:  ["https://example.com"]
        allow_methods: ["POST", "PUT", "GET", "DELETE", "OPTIONS"]
        allow_headers: ["content-type", "authorization"]
        max_age:       3600
    paths:
        '^/': ~

# app/config/security.yml

security:
    # ...
    firewalls:
        login:
            pattern:  ^/login$
            stateless: true
            anonymous: true
            form_login:
                check_path: /login
                success_handler: lexik_jwt_authentication.handler.authentication_success
                failure_handler: lexik_jwt_authentication.handler.authentication_failure
            require_previous_session: false

        api:
            pattern:   ^/
            stateless: true
            lexik_jwt: ~

    access_control:
        - { path: ^/, roles: ROLE_ANONYMOUS, methods: [GET] }
        - { path: ^/special, roles: ROLE_USER }
        - { path: ^/, roles: ROLE_ADMIN }

Specs and tests with Behat

Behat and its Behatch extension make testing and API easy.

# features/put.feature
Scenario: Update a resource
    When I send a "PUT" request to "/people/1" with body:
    """
    {
      "name": "Kevin"
    }
    """
    Then the response status code should be 200
    And the response should be in JSON
    And the header "Content-Type" should be equal to "application/ld+json"
    And the JSON should be equal to:
    """
    {
      "@context": "/contexts/Person",
      "@id": "/people/1",
      "@type": "Person",
      "name": "Kevin",
      "address": null
    }
    """

Tools for the static webapp

Angular, React, Ember, Backbone or anything else
Restangular
Auth0 JWT libraries
Yeoman, Gulp or Grunt, Bower, Jasmine, Karma...

A JavaScript client

'use strict';

angular.module('myApp')
    .controller('MainCtrl', function ($scope, Restangular) {
        var peopleApi = Restangular.all('people');

        function loadPeople() {
            peopleApi.getList().then(function (people) {
                $scope.people = people;
            });
        }

        loadPeople();

        $scope.newPerson = {};
        $scope.success = false;
        $scope.errorTitle = false;
        $scope.errorDescription = false;

        $scope.createPerson = function (form) {
            peopleApi.post($scope.newPerson).then(function () {
                loadPeople();

                $scope.success = true;
                $scope.errorTitle = false;
                $scope.errorDescription = false;

                $scope.newPerson = {};
                form.$setPristine();
            }, function (response) {
                $scope.success = false;
                $scope.errorTitle = response.data['hydra:title'];
                $scope.errorDescription = response.data['hydra:description'];
            });
        };
    });

This is an AngularJS controller displaying the list of people returned by the API and handling a form to create a new person.

The Restangular library is used to retrieve data from the /people route. The base URL of the API should be configured in the application bootstrap file.

In the loadPeople function, Restangular is used to retrieve the first page of the collection. The getList function returns a promise. When it is resolved, the API response is automatically parsed and converted to an array of JS documents. This array is bind to the view using the Angular scope.

The view contains a form bind to the newPerson property of the Angular scope. When the createPerson function is called (for instance when a button is pressed) Restangular serialize the object to JSON and send it to the API.

If an error is returned, the client leverages the API Platform error serialization feature to display a user friendly message.