Unzählige Tools in allen Sprachen unterstützen einen dabei, solide APIs zu bauen, aber die Symfony-basierte api-platform sticht hervor: mit ihr erstellt man OpenAPI-kompatible REST-Schnittstellen nur mit Hilfe von einfachen Code-Annotationen. Stefan präsentiert zunächst die Basisinstallation des Frameworks und stellt seine wichtigsten Features vor, um dann tiefer in produktive Details einzusteigen. Darunter, wie man Client-Code und SPA-Frontends automatisch generiert, datenbankbasierte Akzeptanztests in Behat und Mink schreibt, sich per JWT authentifiziert, Custom Endpoints erstellt und von Doctrine ORM unabhängige Datenquellen nutzt. Schließlich demonstriert er, wie sich die produktive Vue.js-SPA seines Projekts via Apollo-Client mit automatisch generierten GraphQL-Endpunkten verbindet, ohne einen einzigen Resolver schreiben zu müssen und wie das brandneue Mercure-Protokoll dafür sorgt, dass das Frontend automatisch mitbekommt, wenn sich Daten auf dem Server ändern.

1. API Platform
Die ultimative API-Plattform

2. Hello, I am
Stefan Adolf
Developer Ambassador
Turbine Kreuzberg
@stadolf
#reactjs #mongodb #blockchain #codingberlin
#elastic #symfony #turbinejetzt #microservices

3. REST
Representational state transfer

© Roy Fielding ~2000

CRUD Operationen auf “Resourcen”
❏ HTTP Verben: GET, POST, DELETE, PUT, PATCH
❏ URIs
❏ Unabhängig vom mediatype: json, xml, html, image/png

Definiert Operationen auf
❏ Collections /products
❏ Members /products/314

Statusloses Protokoll
❏ Ein Request muss alles enthalten, was für
die Antwort erforderlich ist.
Roy

4. HATEOAS
Hypermedia as the engine of application state

Responses enthalten “Links” auf verwandte Resourcen
❏ Welche Links angeboten werden, hängt vom Status der Resource ab

Clients entscheiden, ob / was sie daraus machen
❏ “code on demand”

6. Product
Offer
Supplier
Reservation
1
0..n
0..n
0..n
+ quantity
+ price
+ sku
+ name
+ customer : string[]

7. GenericRESTAPIsinSymfony
DIY

8. Doctrine Annotations!
Reicht das nicht ??

9. API Platform is a set of tools to
build and consume web APIs
Kevin
API Platform generiert APIs aus
bereits existierenden Entitäten
Stefan

10. @ApiResource
Exponiert Entitäten als Resource (CRUD)

12. @ApiFilter

SearchFilter
❏ partial, start, end, word_start

DateFilter
❏ (strictly_) after, before

BooleanFilter

RangeFilter
❏ lt,gt, lte, gte, between

Unterstützt auch nested properties!
❏ @ApiFilter(RangeFilter::class, properties={"offers.price"})

13. @Assert

API Platform erkennt
Symfony Constraints

Fehlermeldungen
erscheinen in der
Ausgabe

14. OpenAPI support (“swagger”)

Version 2 & 3
 /docs.json?<spec_version=3>

Schema-Definition von
❏ Interaktionen
❏ Datenmodell
❏ Relationen
bin/console api:swagger:export --spec-version=2 --output=swagger.json

Automatische Dokumentation
❏ + interaktiver Playground

Client-Codegeneration (!)

Stub-Generation für Server-
Implementierungen

Test-Automation

15. Interaktive Dokumentation
(nelmio/api-doc-bundle & redoc)

16. application/json

17. JSON-LD
JSON for linking data
Data is messy and disconnected.
JSON-LD organizes and connects it,
creating a better Web. Hydra is a lightweight vocabulary to create
hypermedia-driven Web APIs.
By specifying a number of concepts commonly used in
Web APIs it enables the creation of generic API clients
Markus
Hydra Core Vocabulary
Relationen, Links & Operationen
Markus Lanthaler

18. application/ld+json
+ hydra core

19. application/hal+json
(Hypertext Application language)
The JSON Hypertext Application Language (HAL)
is a standard which establishes conventions for
expressing hypermedia controls, such as links,
with JSON

20. application/vnd.api+json
JSON:API
A SPECIFICATION FOR BUILDING APIS IN JSON
If you’ve ever argued with your team about the way
your JSON responses should be formatted,
JSON:API can be your anti-bikeshedding tool.

22. Generierung von (backend) Client Code
via swagger-codegen

23. Automatisch generierte Frontends
react/redux, vue, (next, quasar, react native)
yarn global add @api-platform/client-generator

24. Validation

25. Fork von react-admin: keinerlei Frontend-Code notwendig!
API Platform Admin

26. Custom endpoints: Deklaration

27. Custom endpoints: Controller

28. Behat-Tests: Konfiguration

29. Behat-Tests: Behatch-Kontext

30. Der Agenturler hatte eine verrückte Idee.
Der wollte mal GraphQL einsetzen.

31. GraphQL
Done.
composer req webonyx/graphql-php

32. GraphQL - Playground

33. Realtime updates
composer require mercure

Installiere einen Mercure Hub
❏ z.B. Docker oder Binary
❏ Plaintext-Secret
❏ JWT mit publish-Eintrag
❏ Bestandteil der offiziellen Distribution
@ApiResource(mercure=true)

34. Realtime updates
GET /products/1 HTTP/1.1
Host: sfliveapi.herokuapp.com
Accept: application/ld+json
Content-Type: application/json
HTTP/1.1 200 OK
Link: <https://sfliveapi.herokuapp.com/docs.jsonld>;
rel="http://www.w3.org/ns/hydra/core#apiDocumentation"
,<https://mercuresflive.stadolf.de/hub>; rel="mercure"

Clients wissen jetzt, dass der Hub sie bei
Änderungen benachrichtigen wird.

35. Realtime updates: client

EventSource = native JS API für Server Sent Events
❏ In allen Browsern verfügbar
❏ Keine externen Dependencies!

36. SSE: Browser support

37. Putting it all together

38. Performance
sfl.stadolf.de

39. Dinge ohne Demo.

docker / docker-compose dev env

Helm Charts für K8S deployment

http/2 push
❏ Der Server sendet verwandte Resourcen selbst an den Client

RDFa-Support / Schema Generator
❏ DRtW: Erzeuge neue Entitäten aus öffentlichen Schemas
❏ YAML-Konfiguration
❏ Schema.org

40. Wrapup

Perfekt für entitätenbasierte APIs

JSON-LD out of the box

Automatische Dokumentation & Clients

Perfekt in Symfony integriert

Killerfeatures per Annotation aktivierbar

GraphQL!

41. Thank you o/
Stefan Adolf
Turbine Kreuzberg
@stadolf
@elmariachi111
https://github.com/elmariachi111/apiplatform-demo/