Le slide del primo Bentosa Happy Monday, il workshop tenuto da Antonio Pintus e Federico Pinna sulle Web API.

1. Happy Monday #1
The Web API guidelines for happy developers
Antonio Pintus & Federico Pinna
1
antonio@bentosa.it - fpinna@bentosa.it

2. The path to HAPPINESS
1. Intro: il nostro credo, le API devono essere belle bellissime
2. Risorse and Collezioni
3. URL, versioni, metodi, status & errori: consistenza
4. Rappresentazioni e formato dei dati
5. Sicurezza di base e Autenticazione
6. Documentazione & SDK
2

3. Happy Monday!
- Antonio Pintus, Technologist al CRS4, CTO di Paraimpu
- Federico Pinna, CTO di Vivocha
3

4. Le regole del gioco
- API first
- Documentazione
- Consistenza
- Sicurezza
- Le API devono essere bellissime (mantra)
4

5. Q&A: la web app
5
github.com/BENTOSA/happy-ask-me
un form per le domande
ma voi usate le API ;)

6. 6
REST
(ripasso veloce)

7. Web API, partiamo da REST
- il termine REST fu introdotto da Roy Fielding nella
sua tesi di dottorato
- REpresentational State Transfer: REST
- Uno stile architetturale per applicazioni distribuite
7

8. REST: concetti principali
- REpresentation: le Risorse sono le astrazioni principali in
REST
- State: focus sullo stato delle risorse
- Transfer: trasferire mediante una interfaccia uniforme le
rappresentazioni delle risorse (e.g., mediante il protocollo
HTTP)
8

9. REST: le Risorse
- le Resource sono i blocchi fondamentali per la costruzione di
sistemi Web-based
- in REST, qualsiasi entità esposta sul Web è una Risorsa:
documents, users, products, books, sensors, things, …
- una Resource deve in qualche modo essere univocamente
identificata e referenziata
9

10. REST: le risorse
- Il Web fornisce il meccanismo degli URI (Uniform
Resource Identifier) per identificare le risorse
rendendole “indirizzabili” mediante un protocollo,
per esempio HTTP
- URI - Resource: relazione many-to-one, un URI
identifica univocamente una sola risorsa ma una
risorsa può avere più URI che la identificano
10

11. REST: risorse e URL
Esempi:
- https://www.cagliariopendata.it/api/v1/stations
- https://www.cagliariopendata.it/api/v1/stations/1
- https://api.stripe.com/v1/customers/cus_8ehF2N1My7FAjP
11

12. REST: risorse e rappresentazioni
- Una representation è una vista (o trasformazione) dello stato
della risorsa referenziata in un dato momento nel tempo
- La particolare vista (content) è espressa in un dato formato:
XML, HTML, JSON, JPEG, ...
- Si specifica il content desiderato utilizzando una content
negotiation (HTTP)
12

13. REST: risorse e rappresentazioni
- https://api.myserver.com/v1/books/1
<book>
<author>J.J. Smith</author>
<author>A. Bell</author>
<ISBN>998765467834276</ISBN>
<publisher>BPress</publisher>
<title>REST Services</title>
<year>2011</year>
</book>
{
"author":["J.J. Smith","A. Bell”],
“ISBN":"998765467834276",
“publisher":"BPress",
"title":"REST Services”,
“year":"2011"
}
XML
JSON
13

14. REST: Uniform Interface
- Uniform Interface, gli stessi metodi HTTP comunemente usati nel
Web: GET, POST, PUT, DELETE, HEAD, …
- sono universali: data una applicazione, non vengono (ri)definiti
metodi specifici (come accade invece nei Web service WS-*, SOAP)
- sono ben definiti e la loro semantica è ampiamente accettata
- si utilizzano i codici d’errore standard di HTTP: 404, 200, 500, ...
14

15. REST: HATEOAS
- Hypermedia As The Engine of Application State
(HATEOAS): le risorse e il loro stato possono essere
“raggiunti” attraverso link presenti nelle rappresentazioni
stesse
- le rappresentazioni delle risorse contengono link (URI) a
rappresentazioni di risorse
- questo permette di navigare per risorse interconnesse
15

16. REST: stateless
- allo scopo di evitare transazioni di lunga durata nelle
applicazioni:
- per le Risorse: lo stato è gestito dal server; se un client
cambia lo stato di una risorsa, tutti i client vedono questo
cambiamento
- per i Client: lo stato del client è mantenuto sul client (stato
specifico del client stesso)
16

17. REST: vantaggi
- come il Web stesso, REST consente un approccio
“loosely-coupled” nella realizzazione delle applicazioni
- questo implica la scalabilità
- è uno stile indipendente dai linguaggi di
programmazione
17

18. REST in pratica
5 principi:
1. assegnare un ID a ciascuna risorsa
2. collegare con un link le risorse
3. usare metodi standard
4. modellare le risorse in modo che abbiano rappresentazioni
multiple
5. usare interazioni stateless tra client e server
18

19. REST: facile, chiaro, bellissimo, seguito da tutti, no?
19

20. REST: Facile, chiaro, bellissimo seguito da tutti, no?
20
NO!

21. Trova le differenze #1
GET /a/vvc_demo/api/_/contacts/get/?cid=aaaa HTTP/1.1
Host: beta.vivocha.com
HTTP/1.1 200 OK
Content-Type: application/json
{
result: false,
status: 401,
vvc: “4.9.1"
}
21
GET /a/vvc_demo/api/v5/contacts/aaaa HTTP/1.1
Host: beta.vivocha.com
HTTP/1.1 401 Unauthorized

22. Trova le differenze #2
GET /use?token=234-566-78b-cde-f12
Host: api.paraimpu.com
22
GET /v1/things/234-566-78b-cde-f12/data
Host: api.paraimpu.com
Ottenere i dati prodotti da un sensore

23. 23
- REST come religione?
- Fondamentalisti del REST o hippie dalla libera interpretazione delle API e
potere alla fantasia?
Quindi?

24. 24
- REST come religione?
- Fondamentalisti del REST o hippie dalla libera interpretazione delle API e
potere alla fantasia?
- Né gli uni né gli altri…
Quindi?
Né gli uni né gli altri…

25. 25
- L’implementazione delle API deve seguire un
approccio più “pragmatico”: principi di REST ma
con un occhio alla praticità di utilizzo
- Non dimentichiamo che le API hanno un’unica
tipologia di fruitori: developers, developers,
developers!
Occorre essere pratici!

26. 26
WEB API: le linee guida
per rendere gli sviluppatori felici (di nuovo)

27. Web API: Risorse, nomi, URL
- Ogni risorsa ha un nome significativo e non ambiguo: User, Book,
Message, Charge
- Ogni risorsa ha il suo URL unico, con
- nomi plurali per le collezioni di risorse
- ogni singola risorsa ha un suo unico identificativo (id)
27

28. Web API: Risorse, nomi, URL
28
/services
/connections
/orders
/books
/sensors/data
/services/1
/connections/4
/orders/ab-d-45
/books/1240-1
/sensors/62/data/550e8400-e29b-41d4-a716-446655440000
collezioni di risorse
singole risorse (id)
{
"id": “1240-1“,
"title":"Web API tips",
“author":"Johnny Joe"
}
rappresentazione di una risorsa Book,
in JSON

29. - l’URL di base delle API deve essere semplice
- L’URL di base delle API deve riportarne la versione
https://api.paraimpu.com/v1
https://api.vivocha.com/v5
https://api.paraimpu.com/v1/things
https://api.vivocha.com/v5/payments
https://www.example.org/api/some-api/v1
https://www.example.org/api/some-api/v2
https://www.example.org/api/other-api/v12
Web API: Risorse, nomi, URL
29

30. - Modello CRUD (Create, Read, Update, Delete)
- non spiazziamo gli sviluppatori
(che sono gli utilizzatori delle nostre API)
- usiamo i metodi HTTP in maniera corretta e coerente
Web API: metodi HTTP
30

31. Web API: metodi HTTP
GET
per ottenere la rappresentazione di
una risorsa
POST per creare una risorsa sul server
PUT per aggiornare una risorsa sul server
DELETE per eliminare una risorsa dal server
31

32. - Esempio di GET:
GET /v1/books HTTP/1.1
Host: api.example.org
HTTP/1.1 200 OK
Content-Type: application/json
[ {
"id": "1",
"title": "Cryptonomicon",
"author": "Neal Stephenson"
}, {
"id": "2",
"title": “Il fasciocomunista",
"author": "Antonio Pennacchi"
} ]
Web API: Metodi HTTP
32

33. - Esempio di POST:
POST /v1/books HTTP/1.1
Host: api.example.org
Content-Type: application/json
{
"title": "Cryptonomicon",
"author": "Neal Stephenson"
}
HTTP/1.1 201 Created
Location: https://api.example.org/v1/books/123
Content-Type: application/json
{
"id": "123",
"title": "Cryptonomicon",
"author": "Neal Stephenson"
}
Web API: Metodi HTTP
33

34. - Esempio di PUT:
PUT /v1/books/123 HTTP/1.1
Host: api.example.org
Content-Type: application/json
{
"title": "Snow Crash",
"author": "Neal Stephenson"
}
HTTP/1.1 200 OK
Content-Type: application/json
Web API: Metodi HTTP
34

35. - Esempi di DELETE:
DELETE /v1/things/123
DELETE /v1/things
Web API: Metodi HTTP
Cancella una risorsa
Cancella tutte le risorse “Thing”
(cancella la collezione)
35

36. Web API: errori e status
36
GET /v1/things/123_bad_id HTTP/1.1
Host: api.example.org
HTTP/1.1 200 OK
Content-Type: application/json
{
"error": "404",
"message": "Not Found"
}

37. 37
NON - FATELO - MAI!

38. Web API: errori e status
38
Utilizzare sempre i codici standard di status e di
errore propri di HTTP

39. Web API: errori e status
39

40. Web API: errori e status
40

41. Web API: errori e status
41

42. Web API: errori e status
42
https://http.cat
API

43. HTTP/1.1 404 Not Found
{
"error": 404,
"errorMessage": "Book not found, maybe the id is wrong",
“moreInfo":"https://docs.mysuperapp.com/v1/support/404"
}
Web API: Metodi HTTP
…e, in caso di errore, restituire un messaggio più dettagliato nel
body della risposta
43

44. Formato dei dati
JSON
44

45. Formato dei dati
- Supportare almeno JSON
- Se si decide di supportare più formati:
- gestire header Accept
Accept: application/json
Accept: text/xml
- gestire estensione nell’url
GET /v1/things/123.json
GET /v1/things/123.xml
45

46. Formato dei dati
Come torturare me o Antonio:
{
“StringA”: “aaa”,
“altra_stringa”: “bbb”,
“eccoUnIntero”: 6,
“odio_indentare”: “aaaaaaah” }
46

47. Formato dei dati
Casi particolari:
- Date, usare il formato ISO 8601:
yyyy-MM-ddTHH:mm:ss.SSSZ
- Undefined, non usare
- Array vuoti, attenzione a MongoDB
47

48. Sicurezza
- Proteggere i dati
- Garantire la continuità del servizio
- Autenticare e autorizzare l’accesso
48

49. Sicurezza
- Sempre e solo HTTPS
- Mai esporre più di quanto strettamente necessario
- Escape/sanitize tutto l’input
- Pentest
- Non reinventare la ruota
49

50. Autenticazione e autorizzazione
- Evitare le sessioni se possibile
- Usare Bearer Tokens
Authorization: Bearer abcd-123-efg-456
- Ancora meglio: usare JSON Web Tokens
Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikp
vaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
- Ma soprattutto: OAuth 2
50

51. Documentazione
- Ripetiamo insieme: le API hanno un’unica tipologia di
fruitori, developers, developers, developers!
- Una bella documentazione deve essere:
- Chiara
- Esaustiva
- Immediata
- Ricca di esempi, possibilmente in linguaggi diversi
51

52. Documentazione
- Il primo problema di una bella documentazione è
che la deve scrivere un developer
- Il secondo problema è che lo stesso developer la
deve anche mantenere aggiornata
E se ci fosse un modo di produrre bella
documentazione (quasi) automaticamente?
52

53. Documentazione
- OpenAPI aka Swagger è un specification format
- Altre sono RAML e API Blueprint
53

54. Documentazione
54
Swagger
JSON Schema
JSON Reference
JSON Pointer

55. Documentazione
Link utili:
- https://openapis.org/
- http://swagger.io/
- https://github.com/swagger-api
- https://github.com/vivocha/jsonpolice
- https://github.com/vivocha/jsonref
55

56. SDK
- (ripetiamolo) gli sviluppatori sono pigri ;)
- Forniamo quindi anche un Software Development Kit (SDK) per i
linguaggi di programmazione più comuni
56

57. happy download
leanpub.com/thewebapinntux
57

58. Q&A app, open source
github.com/BENTOSA/happy-ask-me
58

59. grazie!
www.bentosa.it
59

60. ONE MORE THING
60

61. Training Workshop
Growth Networking
www.bentosa.it
61