REST easy with API Platform

REST easy with API
Platform
Antonio Perić-Mažar, Locastic

12.04.2019., #DevConMu

Antonio Perić-Mažar
CEO @ Locastic
Co-Founder @ Blockada
antonio@locastic.com
@antonioperic

Locastic
• We help clients create amazing web and mobile apps (since 2011)
• mobile development
• web development
• UX/UI
• Training and Consulting
• Shift Conference, Symfony Croatia
• www.locastic.com t: @locastic

The web has changed
• Javascript web apps are standard (SPA)
• Users spend more time on using mobile devices than desktop or TV.
• Linked Data and the semantic web are a reality

APIs are the heart of this new web
• Central point to access data (R/W data)
• Encapsulate business logic
• Same data and same features for desktops, mobiles, TVs and etc
• It is stateless (PHP Sessions make horizontal scaling harder)

Client Apps
• HTML5 (SPA), mobile apps, TVs, Cars etc.
• Holds all the presentation logic
• Is downloaded ﬁrst (SPA, shell model)
• Queries the API to retrieve and modify data using asynchronous requests
• Is 100% composed of HTML, JavaScript and assets (CSS and etc)
• Can be hosted on a CDN

Immediate beneﬁts
• Speed (even on mobile)
• Scalability and robustness
• Development comfort
• Long term beneﬁts

HTTP + REST + JSON
• Work everywhere
• Lightweight
• Stateless
• HTTP has a powerful caching model
• Extensible (JSON-LD, Hydra, Swagger, HAL…)
• High quality tooling

HATEOAS / Linked Data
• Hypermedia as the Engine of Application State
• Hypermedia: IRI as identiﬁer
• Ability to reference external data (like hypertext links)
• Auto discoverable <=> Generic clients

JSON-LD (JSON for Linked Data)
• Standard: W3C recommandation (since 2014)
• Machine readable data
• Easy to use: looks like a typical JSON document
• Already used by Gmail, GitHub, BBC, Microsoft, US gov…
• Compliant with technologies of the semantic web: RDF, SPARQL, triple
store…
• Good for SEO

Hydra
• Describe REST APIs in JSON-LD
• = write support
• = auto-discoverable APIs
• = standard for collections, paginations, errors, ﬁlters
• Draft W3C (Work In Progress)

{
"@context": "/contexts/Book",
"@id": "/books/2",
"@type": "http://schema.org/Book",
"id": 2,
"isbn": "9790070863971",
"description": "A long but very interesting story about REST and asyncio.",
"author": "The life!",
"title": "X",
"publicationDate": "2002-01-29T00:00:00+00:00"
}

{
"@context": "contexts/Errors",
"@type": “hydra:Error”,
“hydra:title”: “An error occurred”,
“hydra:description”: “Not found”
}

{
"@context": "/contexts/Book",
"@id": "/books",
"@type": "hydra:Collection",
"hydra:member": [
{
"@id": "/books/2",
"id": 2,
"isbn": "9790070863971",
"description": "A long but very interesting story about REST and asyncio.",
"author": "The life!",
"title": "X",
},
…
{
"@id": "/books/31",
"id": 31,
"isbn": "9791943452827",
"description": "Tempora voluptas ut dolorem voluptates. Provident natus ipsam fugiat est ipsam quia. Sint mollitia sed facere qui
sit. Ad iusto molestias iusto autem laboriosam nulla earum eius.",
"author": "Miss Gladyce Nader I",
"title": "Voluptas doloremque esse dolor qui illo placeat harum voluptatem.",
}
],
"hydra:totalItems": 125,
"hydra:view": {
"@id": "/books?page=1",
"@type": "hydra:PartialCollectionView",
"hydra:first": "/books?page=1",
"hydra:last": "/books?page=5",
"hydra:next": "/books?page=2"
}
}

“API Platform is the most
advanced API platform, in any
framework or language.”
Fabien Potencier, SymfonyCon 2017

API Platform: the promise
• Fully featured API supporting Swagger + JSON-LD + Hydra + HAL in minutes
• An auto generated doc
• Convenient API spec and test tools using Behat
• Easy authentication management with JWT or OAuth
• CORS and HTTP cache
• All the tools you love: Doctrine ORM, Monolog, Swiftmailer...

API Platform <3 Symfony
• Built on top of Symfony full-stack
• Install any existing SF bundles
• Follow SF Best Practices
• Use your Symfony skills
• Can be used in your existing SF app
• (Optional) tightly integrated with Doctrine

Features
• CRUD
• Filters
• Serializations groups and relations
• Validation
• Pagination
• Sorting
• The event system
• Content Negation
• Extensions
• HTTP and reverse proxy caching
• Invalidation-based HTTP caching
• JS Admin apps
• GraphQL support
• And basically everything needed to build
modern APIs

How to start?
• Download distribution and use Docker (includes frontend applications, etc)
• https://github.com/api-platform/api-platform/releases/tag/v2.4.2
• Use Symfony Flex and any setup you want (little harder to setup)
• Enjoy!!!

CRUD
<?php
namespace AppEntity;
class Author
{
private $id;
private $firstName;
private $lastName;
// ...
}
# api/config/packages/api_platform/
author.yaml
resources:
AppEntityAuthor:~

{
"@context": "http://schema.org",
"@type": "FlightReservation",
"reservationNumber": "RXJ34P",
"reservationStatus": "http://schema.org/Confirmed",
"underName": {
"@type": "Person",
"name": "Eva Green"
},
"reservationFor": {
"@type": "Flight",
"flightNumber": "110",
"airline": {
"@type": "Airline",
"name": "United",
"iataCode": "UA"
},
"departureAirport": {
"@type": "Airport",
"name": "San Francisco Airport",
"iataCode": "SFO"
},
"departureTime": "2017-03-04T20:15:00-08:00",
"arrivalAirport": {
"@type": "Airport",
"name": "John F. Kennedy International Airport",
"iataCode": "JFK"
},
"arrivalTime": "2017-03-05T06:30:00-05:00"
}
}

Using schema.org in Api Platform
resources:
AppEntityFlightReservation:
iri: 'http://schema.org/FlightReservation'

Using schema.org in Api Platform
resources:
AppEntityFlightReservation:
iri: 'http://schema.org/FlightReservation'
properties:
status:
iri: 'http://schema.org/reservationStatus'

Operations
• API Platform Core relies on the concept of operations. Operations can be
applied to a resource exposed by the API. From an implementation point of
view, an operation is a link between a resource, a route and its related
controller.
• There are two types of operations:
• Collection operations act on a collection of resources. By default two
routes are implemented: POST and GET.
• Item operations act on an individual resource. 3 default routes are
deﬁned GET, PUT and DELETE.

Custom operation
class Match
{
private $id;
/**
* @Groups({"match_read"})
*/
private $datetime;
/**
* @Groups({"match_read", "match_write"})
*/
private $playerOnePoints;
/**
*/
private $playerTwoPoints;
/**
*/
private $playerOne;
/**
*/
private $playerTwo;
/**
*/
private $winner;
/**
*/
private $result;
}

Custom operationclass Match
{
private $id;
/**
*/
private $datetime;
/**
*/
/**
*/
/**
*/
private $playerOne;
/**
*/
private $playerTwo;
/**
*/
private $winner;
/**
*/
private $result;
}
class MatchController extends Controller
{
/**
* @param Match $data
*
* @return Match
*/
public function getMatchAction($data)
{
$result = $data->getPlayerOne() . ' ' . $data->getPlayerOnePoints().':'
.$data->getPlayerTwoPoints() . ' ' . $data->getPlayerTwo();
$data->setResult($result);
return $data;
}
}

Custom operation
class Match
{
private $id;
/**
*/
private $datetime;
/**
*/
/**
*/
/**
*/
private $playerOne;
/**
*/
private $playerTwo;
/**
*/
private $winner;
/**
*/
private $result;
}
class MatchController extends Controller
{
/**
* @param Match $data
*
* @return Match
*/
public function getMatchAction($data)
{
$result = $data->getPlayerOne() . ' ' . $data->getPlayerOnePoints().':'
.$data->getPlayerTwoPoints() . ' ' . $data->getPlayerTwo();
$data->setResult($result);
return $data;
}
}
# app/config/routing.yml
get_match:
path: /api/v1/matches/{id}.{_format}
methods: ['GET']
defaults:
_controller: AppBundle:Match:getMatch
_api_resource_class: AppBundleEntityMatch
_api_item_operation_name: get

Override default order
resources:
AppEntityPlayer:
attributes:
order:
lastname: ‘ASC’

Adding subresource
resources:
AppBundleEntityPlayer:
properties:
matches:
subresource:
resourceClass: ‘AppEntityMatch’
maxDepth: 1
collection: true
-> api.com/players/1/matches

Filters
• If Doctrine ORM support is enabled, adding filters is as easy as registering
a filter service in your api/config/services.yml file and adding an
attribute to your resource configuration.
• Filters add extra conditions to base database query
• Useful filters for the Doctrine ORM are provided with the library. You can
also create custom filters that would fit your specific needs.

Filters examples
# AppBundle/Resources/config/api_resources/resources.yml
resources:
AppBundleEntityPlayer:
# ...
attributes:
filters: ['player.search', 'player.order']
AppBundleEntityMatch:
# ...
attributes:
filters: ['match.date']
services:
player.search_filter:
parent: 'api_platform.doctrine.orm.search_filter'
arguments: [ { id: 'exact', email: 'exact', firstName: 'partial' } ]
tags: [ { name: 'api_platform.filter', id: 'player.search' } ]
match.date_filter:
parent: 'api_platform.doctrine.orm.date_filter'
arguments: [ { datetime: ~ } ]
tags: [ { name: 'api_platform.filter', id: 'match.date' } ]
player.order_filter:
parent: 'api_platform.doctrine.orm.order_filter'
arguments: [{ firstName: 'ASC', lastName: 'ACS', email: ~ }]
tags: [{ name: 'api_platform.filter', id: 'player.order' }]

Serialization Groups
• API Platform Core allows to choose which attributes of the resource are
exposed during the normalization (read) and denormalization (write)
process. It relies on the serialization (and deserialization) groups feature of
the Symfony Serializer component.
• allows to specify the deﬁnition of serialization using XML, YAML, or
annotations.

<?php
namespace AppEntity;
use FOSUserBundleModelUser as BaseUser;
use SymfonyComponentSerializerAnnotationGroups;
class Player extends BaseUser
{
/**
* @var int
*/
protected $id;
/**
* @Groups({"player_read", "player_write"})
*/
private $firstName;
/**
*/
private $lastName;
/**
*/
protected $email;
// ...
}
# UserBundle/Resources/api_resources/resources.yml
resources:
AppEntityPlayer:
attributes:
normalization_context:
groups: ['player_read']
denormalization_context:
groups: ['player_write']

Using Different Serialization
Groups per Operation
# UserBundle/Resources/api_resources/resources.yml
resources:
AppEntityPlayer:
itemOperations:
get:
method: 'GET'
groups: ['player_read', 'player_extra']
put:
method: 'PUT'
delete:
method: 'DELETE'
attributes:
groups: ['player_read']
denormalization_context:
groups: ['player_write']

// src/AppBundle/EventSubscriber/MatchEventSubscriber.php
class MatchEventSubscriber implements EventSubscriberInterface
{
private $matchHelper;
public function __construct(MatchHelper $matchHelper)
{
$this->matchHelper = $matchHelper;
}
public static function getSubscribedEvents()
{
return [
KernelEvents::VIEW => [['addWinner', EventPriorities::POST_VALIDATE]],
];
}
public function addWinner(GetResponseForControllerResultEvent $event)
{
$match = $event->getControllerResult();
$method = $event->getRequest()->getMethod();
if(!$match instanceof Match || $method !== 'POST') {
return;
}
$winner = $this->matchHelper->getWinner($match);
$match->setWinner($winner);
}
}

Extensions
• API Platform Core provides a system to extend queries on items and
collections.
• Custom extensions must implement
the ApiPlatformCoreBridgeDoctrineOrmExtensionQuery
CollectionExtensionInterface and / or
the ApiPlatformCoreBridgeDoctrineOrmExtensionQuery
ItemExtensionInterface interfaces, to be run when querying for a
collection of items and when querying for an item respectively.

class GetPlayersExtension implements QueryCollectionExtensionInterface, QueryItemExtensionInterface
{
public function applyToItem(
QueryBuilder $queryBuilder,
QueryNameGeneratorInterface $queryNameGenerator,
string $resourceClass,
array $identifiers,
string $operationName = null,
array $context = []
) {
$this->addWhere($queryBuilder, $resourceClass, $operationName);
}
public function applyToCollection(
QueryBuilder $queryBuilder,
QueryNameGeneratorInterface $queryNameGenerator,
string $resourceClass,
string $operationName = null
) {
$this->addWhere($queryBuilder, $resourceClass, $operationName);
}
private function addWhere(QueryBuilder $queryBuilder, string $resourceClass, string $operationName = null)
{
if ($resourceClass != Player::class || $operationName != 'get') {
return;
}
$rootAlias = $queryBuilder->getRootAliases()[0];
$queryBuilder->andWhere(
$queryBuilder->expr()->eq($rootAlias.'.enabled', ':enabled')
)->setParameter('enabled', true);
}
}

services:
app.extension.get_players:
class: AppBundleDoctrineORMExtensionGetPlayersExtension
public: false
tags:
- { name: api_platform.doctrine.orm.query_extension.collection, priority: 9 }
- { name: api_platform.doctrine.orm.query_extension.item }

Per Resource Authorization Mechanism
namespace AppBundleEntity;

use ApiPlatformCoreAnnotationApiResource;
use DoctrineORMMapping as ORM;

/**
* @ApiResource(
*     attributes={"is_granted"="has_role('ROLE_ADMIN')"},
*     itemOperations={
*         "get"={"method"="GET", "is_granted"="object.getOwner() == user"}
*     }
* )
* @ORMEntity
*/
class Secured
{
    /**
     * @ORMColumn(type="integer")
     * @ORMId
     * @ORMGeneratedValue(strategy="AUTO")
     */
    public $id;

    /**
     * @ORMColumn(type="text")
     */
    public $owner;

Translation Support
• https://github.com/Locastic/ApiPlatformTranslationBundle
• https://locastic.com/blog/having-troubles-with-implementing-translations-in-
apiplatform/

GraphQL Support
• docker-compose exec php composer req webonyx/graphql-php && docker-
compose exec php bin/console cache:clear
• The GraphQL implementation supports queries, mutations, 100% of the
Relay server speciﬁcation, pagination, ﬁlters and access control rules. You
can use it with the popular RelayJS and Apollo clients.

Testing
• PHPUnit
• Postman (newman)
• Panther
• https://locastic.com/blog/what-to-do-when-you-get-lost-in-api-testing/

Mercure
• Fast, written in Go
• native browser support, no lib nor SDK required (built on top of HTTP and server-sent events)
• compatible with all existing servers, even those who don't support persistent connections
(serverless architecture, PHP, FastCGI...)
• Automatic HTTP/2 and HTTPS (using Let's Encrypt) support
• CORS support, CSRF protection mechanism
• Cloud Native, follows the Twelve-Factor App methodology
• Open source (AGPL)
• …

Let’s try it
https://symfonycon.les-tilleuls.coop/

Update progressive web app
• docker-compose exec client generate-api-platform-client
• Follow instructions

Version 2.4
• read and write support for MongoDB, the reference document database,
including a lot of useful ﬁlters
• Read support for Elasticsearch, the open source search and analytics
engine, including ﬁlters for advanced search
• Automatic “push” of updated resources from the server to the clients using
the brand new Mercure protocol

Version 2.4
• Integration with the Symfony Messenger component to easily implement the
CQRS pattern and to handle messages asynchronously (using brokers such as
RabbitMQ, Apache Kafka, Amazon SQS or Google PubSub)
• Ability to leverage the “Server Push” feature of HTTP/2 to preemptively send the
relations of a requested resource to the client
• Automatic availability of list ﬁlters in the React-based admin when a corresponding
one is available API-side
• Full compatibility with the version 3 of the OpenAPI speciﬁcation format (formerly
known as Swagger), and integration of the beautiful ReDoc documentation generator

Version 2.4
• Improved DTOs support
• Per resource conﬁguration of HTTP cache headers
• Ability to easily use the Sunset HTTP header to advertise the removal date
of deprecated endpoints

GFNY Ticketing system
• 20 races, 18 countries
• Different timezones, currencies, languages…
• More then 60 000 tickets per year, with very complex login
• Standings and rankings
• Email notiﬁcation, ﬂexibility
• Etc.

Conclusion
• Very powerful, even for large applications
• Easy to start, well documented
• Active community and company behind it
• Write tests!

antonio@locastic.com
@antonioperic
www.locastic.com
Questions?

REST easy with API Platform

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Semelhante a REST easy with API Platform

Semelhante a REST easy with API Platform (20)

Mais de Antonio Peric-Mazar

Mais de Antonio Peric-Mazar (20)

Último

Último (20)

REST easy with API Platform