graphql, das bessere rest?...graphql? "graphql is a query language for apis and a runtime for...

Die Beschaffungsplattform fur Geschaftskunden

GraphQL, das bessere REST?Jorg Adler, Benjamin Otto, 29.9.2017

Wir @ Mercateo

Mercateo ist Europas fuhrende Beschaffungsplattform.

> 1 Mio. Geschaftskunden

21 Mio. Artikel

mehr als 10.000 Hersteller

Entwicklung von der Beschaffungsplattform zur Transaktionsplattform

Massive Veranderungen in der IT-Landschaft

Jorg [email protected]@joerg adler

Benjamin [email protected]

@ otbe

Die Beschaffungsplattform fur Geschaftskunden 2

Wir @ Mercateo

Mercateo ist Europas fuhrende Beschaffungsplattform.

> 1 Mio. Geschaftskunden

21 Mio. Artikel

mehr als 10.000 Hersteller

Entwicklung von der Beschaffungsplattform zur Transaktionsplattform

Massive Veranderungen in der IT-Landschaft

Jorg [email protected]@joerg adler

Benjamin [email protected]

@ otbe

Beispiel

Nachfolgend beziehen sich alle Folien auf das folgende Beispiel

Order API

Order mit id, state und articles

Order mit States”processing“,

”canceled“,

”shipped“,

”returned“

Ubergang processing → canceled (optional)

Ubergang processing → shipped → returned (optional)

Implementiertes Java-Beispiel:https://github.com/Mercateo/rest-demo-feature/

Beispiel

Order API

”canceled“,

”shipped“,

”returned“

Beispiel

Order API

”canceled“,

”shipped“,

”returned“

Beispiel

Order API

”canceled“,

”shipped“,

”returned“

Beispiel

Order API

”canceled“,

”shipped“,

”returned“

Beispiel

Order API

”canceled“,

”shipped“,

”returned“

GraphQL

Was ist GraphQL?

GraphQL

”GraphQL is a query language for APIs and a runtime for fulfilling thosequeries with your existing data.”

gedacht als dunner API Layer zwischen Client und Backend

initialer Draft von 2015 von Facebook

Spec (OWFA 1.0) + Referenzimplementierung (MIT) auf Github verfugbar

wird seither als Community Draft weiterentwickelt

GraphQL Schema als Contract zwischen Client und Server

GraphQL

Schema

Schema besteht aus Query, Mutation und Subscription

Primitive Datentypen: Int, Float, String, Boolean, ID

Neue Datentypen konnen mit scalar, type, interface, union, enum oder inputdefiniert werden

Cheat Sheet https://github.com/sogko/graphql-schema-language-cheat-sheet

GraphQL

Schema

GraphQL

Schema

GraphQL

Schema

GraphQL

Status Quo

GraphQL

Status Quo

Transport: HTTP POST* auf /graphql Endpoint mit Query im Body

* dadurch ist Caching schwierig; allerdings kann auch GET mit QueryParameter verwendet werden oder Persisted Queries

”one query to rule them all“- beliebig tief geschachtelte Queries konnen

geschrieben werden

Tooling

GraphQL

Status Quo

geschrieben werden

Tooling

GraphQL

Status Quo

geschrieben werden

Tooling

GraphQL

Status Quo

geschrieben werden

Tooling

GraphQL

Tooling - GraphiQL

GraphQL

Tooling - Launchpad

GraphQL

Tooling - Apollo Dev

GraphQL

Tooling - graphql-faker

GraphQL

Status Quo

geschrieben werden

Tooling

Wer nutzt GraphQL?

GraphQL

Beispiel

https://launchpad.graphql.com/x45n51lwl

GraphQL

Beispiel

Datenbeschreibung

1 enum STATE {2 SHIPPED

3 PROCESSING

4 CANCELED

5 RETURNED

8 type Order {9 id: ID!

10 state: STATE

11 articles: [Article]!

12 }13

14 type Query {15 orders(limit: Int, offset: Int): [Order]!

GraphQL

Beispiel

Datenbeschreibung

3 PROCESSING

4 CANCELED

5 RETURNED

10 state: STATE

12 }13

Anfrage

1 {2 orders {3 id

4 state

5 }6 }

GraphQL

Beispiel

Datenbeschreibung

3 PROCESSING

4 CANCELED

5 RETURNED

10 state: STATE

12 }13

Anfrage

1 {2 orders {3 id

4 state

5 }6 }

Ergebnis

1 {2 "orders": [ {3 "id": "1234567",

4 "state": "PROCESSING"

Einfuhrung

REST ist eine Architektur

es gibt keinen (Implementierungs-)Standard, nur Constraints (Client-Server,Stateless, Cache, Uniform Interface, Layered System, Code on Demand)

speziell die Forderung nach einem uniformen Interface macht REST langsam

”The trade-off, though, is that a uniform interface degrades efficiency, since

information is transferred in a standardized form rather than one which isspecific to an application’s needs.“

Fielding, Roy T., Dissertation

”Software design on the scale of decades: every detail is intended to promote

software longevity and independent evolution. Many of the constraints aredirectly opposed to short-term efficiency.“

Fielding, Roy T. “REST APIs must be hypertext-driven“

Einfuhrung

HATEOAS

Hypermedia as the Engine of Application State

integraler Bestandteil von REST

”REST is defined by four interface constraints: identification of resources;

manipulation of resources through representations; self-descriptive messages;and, hypermedia as the engine of application state“

Zustandsubergange am Client ausschließlich uber Links vom Server

Links kommen nur dynamisch vom Server

im Client nur eine Einsprungs-URL und das Wissen uber die Linknamen

HATEOAS

Ist GraphQL nun das bessere REST?

Es ist nicht vergleichbar.

Ist GraphQL nun das bessere REST?Es ist nicht vergleichbar.

Vielen Dank fur Ihre Aufmerksamtkeit :)

Domain Driven Design

hilft beim Schnitt von Microservices

wir legen hier Wert auf die Abgrenzung von Bounded Contexts

auch fur Monolithen mit Schnittstellen wichtig

Businesslogik am Server kapseln

REST-Naiv

reines CRUD

1 GET /orders/1

2 {3 "id": "1",

4 "articles": ...,

5 "state": "SHIPPED"

1 PUT /orders/1

2 {3 "id": "1",

4 "articles": ...,

5 "state": "RETURNED",

Es muss dokumentiert werden, wann welche Statusubergange moglich sind

Alle Clients implementieren dafur Code

Businesslogik sehr schwer anderbar

REST-Naiv

reines CRUD

1 GET /orders/1

2 {3 "id": "1",

4 "articles": ...,

1 PUT /orders/1

2 {3 "id": "1",

4 "articles": ...,

REST-Naiv

reines CRUD

1 GET /orders/1

2 {3 "id": "1",

4 "articles": ...,

1 PUT /orders/1

2 {3 "id": "1",

4 "articles": ...,

REST-HATEOAS

Entscheidung wann etwas moglich ist kommt vom Server uber Links

1 GET /orders/1

2 {3 "id": "1",

4 "articles": ...,

6 "_links": {7 "return": { "href": "/ orders/1" }8 }9 }

Es muss dokumentiert werden, welche und wie Statusubergange moglich sind

Clients konnen uniform feststellen, wann Statusubergange moglich sind

REST-HATEOAS

1 GET /orders/1

2 {3 "id": "1",

4 "articles": ...,

REST-HATEOAS

1 GET /orders/1

2 {3 "id": "1",

4 "articles": ...,

HATEOAS und Schema II

mit Schema: CRUD wird etwas abgemildert

mit Schema: Clients konnen flexibel auf Payloadanderungen reagieren

1 GET /orders/1

2 {3 "id": "1",

4 "articles": ...,

6 "_schema": {7 "links": [

8 { "href": "http:// localhost:9090/orders/1",

9 "schema": { "type": "object",

10 "properties": {11 "state": { "type": "string",

12 "enum": ["RETURNED"] }}},13 "rel": "return",

14 "method": "PATCH"}]}}

REST-HATEOAS ohne CRUD

zusatzlich sollte ein Update von komplexen Ressourcen nicht moglich sein

Man erstellt eine Art ”Kommando”

Welches Kommando man erstellen darf, wird uber Links kommuniziert

Die Implementierung wird hier sehr viel einfacher, kein ratseln am Server mehr

Zusatzliche Daten konnen erhoben werden

HATEOAS und Schema

1 GET /orders/1

3 { "href": "http:// localhost:9090/returns",

4 "schema": {"type": "object",

5 "properties": {6 "id": {"type": "uuid"},7 "message": {"type": "string"},8 "orderId": {"type": "string",

9 "enum": ["1"]}},10 "required": ["message","orderId","id"]},11 "method": "PUT",

12 "rel": "return"}...

GraphQL-Naiv

reine CRUD Mutations

1 createOrder(order)

2 updateOrder(order)

Kommt bekannt vor? :)

GraphQL-Naiv

GraphQL Commands

Kein CRUD mehr

1 cancelOrder(orderId: ID!, message: String)

2 returnOrder(orderId: ID!, message: String)

Es muss immer noch dokumentiert werden, wann welche Statusubergangemoglich sind

Reduziert Komplexitat im Client und Server

GraphQL Commands

Kein CRUD mehr

GraphQL Commands

Kein CRUD mehr

GraphQL HATEOAS Extensions

Wie konnen wir darstellen, welche Statusubergange im aktuellen Zustandmoglich sind?

→ Relay-Style Pagination

→ Statusinformationen in den Kanten

1 {2 orders {3 edges {4 node {5 id

6 state

11 }12 }13 }

→ Relay-Style Pagination → Statusinformationen in den Kanten

6 state

11 }12 }13 }

6 state

9 returnOrder

10 cancelOrder

11 }12 }13 }

Command/Query Responsibility Segregation

Trennung von Kommandos (Schreiben) und Querys (Lesen)

auf Modellierungs- und Deploymentebene

dadurch getrennt entwickelbar, skalierbar, deploybar

Voraussetzung fur Eventsourcing

Bedeutet aber auch Aufwand! Nutzen abwagen.

Mit Ressourcen auf Command-Ebene geht dies sehr gut

Aufpassen bei Ruckgabe von PUT/POST

Auf naturliche Weise kann Eventsourcing unterstutzt werden

Mit Ressourcen auf Command-Ebene geht dies sehr gut

Aufpassen bei Ruckgabe von PUT/POST

Auf naturliche Weise kann Eventsourcing unterstutzt werden

REST II

auch spatere Einfuhrung moglich.

1 PUT /returns ...

2 {3 "_links": {4 "canonical": { "href": "/ returns/4?eventSeq=47" }5 }6 }

GraphQL

Mutations (als Commands) sind bereits von Queries getrennt

Grundsatzlich kann bei einer Mutation ein beliebiges Objektgelesen/zuruckgegeben werden

Im Relay Umfeld werden haufig alle abhangigen Anderungen gelesen damit derClient die Caches updaten kann

Alternative: Mutation + Subscription nutzen

GraphQL

API First

in GraphQL ist das Schema fester Bestandteil des Standards

Entwickler von Server und Client haben dies jederzeit, API first at its best.

API-First Hilfsmittel fur REST prinzipiell vorhanden (Open-API 3.0,Json-Hyperschema, RAML)

native Unterstutzung nur fur statische Links

Bei beiden: HATEOAS mit dynamischen Links erfordert basteln

API First

Disclaimer

Man kann auch fur REST auf wenige Requests optimieren

durch Schaffen von sehr großen Read-Only Ressourcendurch eingebettete Ressourcen (siehe zum Beispiel HAL-Format)durch Auflosen von Links bis zu einer gewissen Tiefe (siehe zum BeispielContentful-API)

alles handischer Aufwand

beim Formulieren von Queries haufig kompliziert

Disclaimer

durch Schaffen von sehr großen Read-Only Ressourcen

durch eingebettete Ressourcen (siehe zum Beispiel HAL-Format)durch Auflosen von Links bis zu einer gewissen Tiefe (siehe zum BeispielContentful-API)

Disclaimer

durch Schaffen von sehr großen Read-Only Ressourcendurch eingebettete Ressourcen (siehe zum Beispiel HAL-Format)

durch Auflosen von Links bis zu einer gewissen Tiefe (siehe zum BeispielContentful-API)

Disclaimer

Wann REST

Firma/Kunden haben sich schon langere Zeit auf REST commitet

in diesem Fall kann man aber trotzdem beides anbieten (schlankesGraph-QL-Lambda vor den REST-Schnittstellen)

HTTP-Caching ist relevant (interne Schnittstellen, offentliche Schnittstellenohne HTTPS,...)

Wann REST

Firma/Kunden haben sich schon langere Zeit auf REST commitet

in diesem Fall kann man aber trotzdem beides anbieten (schlankesGraph-QL-Lambda vor den REST-Schnittstellen)

HTTP-Caching ist relevant (interne Schnittstellen, offentliche Schnittstellenohne HTTPS,...)

Wann GraphQL

man mochte eine hohe Standardisierung in Schnittstellen-Design und Tooling

Performance spielt wesentliche Rolle (Frontends, ...)

Umfeld akzeptiert neue Herangehensweisen

”If your API is not using hypermedia controls, then GraphQL could be a more

relevant approach, because you weren’t really using REST anyway.“

Phil Sturgeon, Platform Engineer @ WeWork

Empfehlung: unbedingt anschauen! :)

Wann GraphQL

Vielen Dank fur Ihre Aufmerksamkeit.

Fragen? :)

Verweise

Seite 10: GraphiQL https://github.com/graphql/graphiql

Seite 11: Launchpad https://launchpad.graphql.com

Seite 12: Apollo Developers http://dev.apollodata.com

Seite 13: graphql-faker https://github.com/APIs-guru/graphql-faker

Seite 15: http://graphql.org/users/

graphql, das bessere rest?...graphql? "graphql is a query language for apis and a runtime for...

Documents