f2-rest seminar april 2014
TRANSCRIPT
RESTful API design
Open Space
April 2014
Jørn Wildt og Jakob Bendsen
cBrain
● ”The Process Company”● 48 ansatte
– 28 udviklere, alle fra Danmark– Master eller Ph.D (DTU, DIKU og ITU)
● C# + MS-SQL + IIS● 50% specialprojekter● 50% standardprodukt (F2)
REST: Et løfte om
Løst koblede
Uafhængige
Skalerbare
Tilgængelige
Distribuerede systemer
Program9.00 Velkomst og præsentationsrunde
9.15 Oplæg: REST (Jakob Bendsen, Lund&Bendsen)
9.45 Pause
10.00 Oplæg: F2 REST og Mason (Jørn Wildt, cBrain)
10.45 Brainstorm på emner
11.00 Open Space Session #1
12.00 Frokost
13.00 Open Space Session #2
14.00 Pause
14.15 Oplæg: Tradeshifts API (Jan Ypma, Tradeshift)
15.00 Pause
15.15 Open Space Session #3
16.15 Pause
16.30 Open Space Session #4
17.30 Wrap up
18.00 Middag
F2 REST / Mason
● F2 demo – digital sagsbehandling● Et par teknikker● F2 REST demo● Mason
F2 Digitaliseringsplatform● Dokumentlagring og deling (fælles arkiv)● Sagsbehandling, aktindsigt og forelæggelser● Fuld e-mail-klient● Ekstern selvbetjening● Indlejret chat (tekst)● Mobil adgang (iOS, HTML)● CPR, Digital Post, ArcGIS, Byg & Miljø, Exchange, AD, GMail● Anvendes hos 8 ministerier, 2 kommuner, en håndfuld
styrelser og nogle enkelte private.
DEMO
● Codebase1.dll● Codebase2.dll● …● CodebaseN.dll● Configuration
Service 1
DB
SQL
● Codebase1.dll● Codebase2.dll● …● CodebaseN.dll● Configuration
Service 2
● Codebase1.dll● Codebase2.dll● …● CodebaseN.dll● Configuration
Service 3
SQLSQL
Før REST
+ Stigende behov forad-hoc integrationer
hos kunderne
F2 REST
Selvbetjening
Mobile
Byg & Miljø
GIS
Kundens integrationer
Operationer● Authentikering● Søgning● Læsning● Opdatering● Oprettelse● Sletning
Data● Sager● Akter● Dokumenter● Parter● Møder
Desktopklient
LinksHTML <a href=”...” rel=”next”>Næste</a>
ATOM <atom:link href=”...” rel=”next” title=”Næste”/>
JSON{
”next”:
{
”href”: ”...”,
”title”: ”Næste”
}
}
Post Once Exactly
● Undgå dobbelte oprettelser● POST 1 => Redirect, factory ressource● POST 2 => Udfør (idempotent), redirect
– Status 201 Created (første gang)– Status 303 See other (efterfølgende)
Hvorfor ikke PUT?
DEMO
JSON-PatchPATCH /my/data HTTP/1.1
Content-Type: application/json-patch+json
If-Match: "abc123"
[
{ "op": "replace", "path": "/Access", "value": ”Open” },
{ "op": "remove", "path": "/a/b/c" },
{ "op": "add", "path": "/a/b/c", "value": [ "foo" ] },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
]
Problemer med F2 REST
● XML matcher dårligt● Udvikler kan ikke udforske actions● Er ikke standardiseret● JSON-Patch er et dårligt match med XML
Findes der et bedre alternativ? Tjah ...
(hyper)media-types
● HAL (JSON + links + link templates)● Siren (JSON + links + key-value-actions)● Collection-JSON (JSON + lister + links + key-
value-actions + error handling)● Hydra (JSON Linked Data)● JSON API (JSON + entiteter)● HTML● ATOM (XML + lister + links)
Mason
● JSON format● Let tilgængeligt● Links● Link templates● Actions (JSON payload + file upload)● Standard fejlhåndtering● Kommunikation til klientudvikler
Curies + Namespaces{
"@namespaces": {
"is": {
"name": "http://issue-tracker.org/reltypes.html#"
}
},
"@links": {
"is:issues": {
"href": "...",
"title": "All issues in project"
}
}
}
DEMO
http://localhost/mason-demo/projects/1
Referencer
● Mason: https://github.com/JornWildt/Mason
● HAL: http://stateless.co/hal_specification.html
● Sirene: https://github.com/kevinswiber/siren ● Coll-JSON: http://amundsen.com/media-types/collection/format/ ● Hydra: http://www.markus-lanthaler.com/hydra/
● JSON-Patch: https://tools.ietf.org/html/rfc6902
Bøger
Kontaktinformation
Jørn Wildt
Twitter @JornWildt
Arbejde: [email protected]
Privat: [email protected]
Blog: http://soabits.blogspot.dk/
LinkedIn: https://www.linkedin.com/in/jornwildt