creating hypermedia apis in a few minutes using the api platform framework
TRANSCRIPT
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! => [email protected]
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