creating hypermedia apis in a few minutes using the api platform framework

API PLATFORMThe PHP framework to buildmodern web APIs.

Kévin DunglasFounder of Les-Tilleuls.coop

Symfony Core Team member

API Platform creator

Teacher at the University of Lille 1

@dunglas

Les-Tilleuls.coopSelf-managed company since 2011100% owned by employees

All benefits are equitably shared between employees18 people, 137% growth in 2015

We are hiring! => jobs@les-tilleuls.coop

The PromiseSupport for modern and future formatsBatteries included: pagination, filtering, auth (JWT, OAuth), HTTP Cache, CORS…UI and automatic documentation (Swagger)Extensible, overridable, customizable

A working API in a few minutes

API: State of the Art

HTTP + REST + JSONWorks easily with all programming languages, on every platformsLightweight (= fast)

Stateless (= scale)

Easy to cache (= faster)

High quality tooling (cURL, Varnish…)

REST: a Pattern, Not a Format

1 project ~= 1 different implementationTedious to create: pagination, filtering, validation, caching, content negotiation, CORS, data interoperability…Hard to reuse server-side tooling (1 API per project)Hard to reuse client-side tooling (1 client per API)Hard to query and aggregate data from different sources

Credit: Martin Fowlerhttp://martinfowler.com/articles/richardsonMaturityModel.html

HATEOAS / Linked Data

Hypermedia: IRIs (e.g. URLs) as identifiers

Ability to reference external data (like hypertext links)

Hypermedia controls (pagination, filtering…)

The road to better server-side tooling and generic clients

Hypermedia as the Engine of Application State

Standards Please!

Swagger / OpenAPI

Describe only I/O formats and available operations for an APIMost popular way to describe APIsLot of tools available (UIs, code generators, validators…)

Open standard (but not endorsed by the W3C)

Not designed for HATEOAS APIs

JSON-LDStandard: W3C recommandation (since 2014)

Easy to use: looks like a typical JSON document

Already chosen by Google, BBC, Microsoft, US gov...

Compliant with technologies of the semantic web: RDF, SPARQL, triple store...

JSON for Linked Data

Schema.org

Large set of elements: people, creative works, events, products, chemicals...Created (and understood by) Google, Bing, Yahoo! et YandexMassively used, and hosted by the W3C (Web schemas group)Supports HTML’s microdata, RDFa and JSON-LD

Open vocabulary for data interoperability at web scale

Extension mechanism, compatible with proprietary/custom vocabularies (yours)

Hydra

Write support (POST, PUT, PATCH…)

Make APIs auto-discoverable (all available operations are documented)A standard for describing collections, paginations, filters, errors…Draft W3C (Work In Progress)

Describe REST APIs in JSON-LD

Getting Started with

API PlatformA framework for the new web.

The PromiseSupport for modern and future formats (JSON-LD, Hydra, HAL, schema.org, API+Problem…)Batteries included: pagination, filtering, auth (JWT, OAuth), HTTP Cache, CORS…Awesome UI and automatic documentation (Swagger)Extensible, overridable, customizable

A working API in a few minutes

InstallGet Docker

If you don’t already have it…

InstallStart the LAMP stack (PHP7, Apache and MySQL)$ docker-compose up# Create the database$ docker-compose exec web bin/console doctrine:schema:create

Go to api-platform.com then click « Download »

Done! Browse http://localhost.

It’s Symfony…

Configured with the most popular librariesfor APIsCompatible with all existing bundlesUse Doctrine ORM by default (but you canuse the persistence system you want)

Symfony full stack application

…with something more

Create your Own Data Model

Write some PHPDoc (optional)

Add the @ApiResource annotation

Map its properties using theDoctrine ORM

Update the database schema

$ docker-compose run web bin/console doctrine:schema:update

--force

Create a Plain Old PHP Object

Your 1st API Platform App is

Up and Running!

Out of the Box Features

JSON-LD + Hydra formatsSwagger documentation

Fully featured UI (working for all URLs of the API)

Create (POST), Retrieve (GET item and lists), Update (PUT) and Delete (DELETE) resources

Pagination for lists (30 items per page), fully configurable

Addvalidation rules

Many validation constraints available

Ability to create custom constraints

Use the Symfony Validatorcomponent

The Schema GeneratorPick an existing data model from (resources and properties) from schema.org:

docker-compose run webvendor/bin/schema generate-types src/ app/config/schema.yml

The Schema Generator

The Schema Generator

PHP classes, properties, getters and setters (PSR compliant)Doctrine ORM mapping (including relations and mapped superclasses)Validation constraintsFull PHPDoc extracted from schema human-readable descriptionsMapping with schema.org's IRIs

The generator uses schema.org data to automatically bootstrap:

Relations between classes (supported by the API system too)

Hypermedia relations

Embedded relations

Embedded relations

Content Negotiation

Adding a new format is as simple as creating a new Symfony Normalizer for it

Built-in formats: JSON-LD, HAL, XML, YAML, CSV, JSON, HTML (UI)

To retrieve a resource in a given format: add an Accept HTTP header or use the format name as file extension

Content Negotiation

Content Negotiation: HAL

Content Negotiation: XML

FiltersRegister the filter service (built-in or custom):

Map the filter to the resource

Filters

The Event System

Events

There is Much More to See

They Already Use API Platform

A Growing Community100+ awesome contributors (code and docs)1.2k stars on GitHub

500+ followers on Twitter

Next Big Things (v2.1)

JSONAPI support

GraphQL support

Native MongoDB support

Your contribution?

Thanks!Any questions?

api-platform/api-platform

@ApiPlatform

https://api-platform.com