Happy Monday #1 The Web API guidelines for happy developers Antonio Pintus & Federico Pinna 1 [email protected] - [email protected]
Happy Monday #1
The Web API guidelines for happy developers
Antonio Pintus & Federico Pinna
1
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
Happy Monday!
- Antonio Pintus, Technologist al CRS4, CTO di Paraimpu
- Federico Pinna, CTO di Vivocha
3
Le regole del gioco
- API first
- Documentazione
- Consistenza
- Sicurezza
- Le API devono essere bellissime (mantra)
4
Q&A: la web app
5
github.com/BENTOSA/happy-ask-me
un form per le domande
ma voi usate le API ;)
6
REST
(ripasso veloce)
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
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
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
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
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
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
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
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
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
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
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
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
REST: facile, chiaro, bellissimo, seguito da tutti, no?
19
REST: Facile, chiaro, bellissimo seguito da tutti, no?
20
NO!
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
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
- REST come religione?
- Fondamentalisti del REST o hippie dalla libera interpretazione delle API e
potere alla fantasia?
Quindi?
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
- 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
WEB API: le linee guida
per rendere gli sviluppatori felici (di nuovo)
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
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
- 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
- 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
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
- 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
- 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
- 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
- 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
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
NON - FATELO - MAI!
Web API: errori e status
38
Utilizzare sempre i codici standard di status e di errore propri di HTTP
Web API: errori e status
39
Web API: errori e status
40
Web API: errori e status
41
Web API: errori e status
42 https://http.catAPI
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
Formato dei dati
JSON
44
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
Formato dei dati
Come torturare me o Antonio:
{ “StringA”: “aaa”, “altra_stringa”: “bbb”, “eccoUnIntero”: 6, “odio_indentare”: “aaaaaaah” }
46
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
Sicurezza
- Proteggere i dati
- Garantire la continuità del servizio
- Autenticare e autorizzare l’accesso
48
Sicurezza
- Sempre e solo HTTPS
- Mai esporre più di quanto strettamente necessario
- Escape/sanitize tutto l’input
- Pentest
- Non reinventare la ruota
49
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
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
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
Documentazione
- OpenAPI aka Swagger è un specification format
- Altre sono RAML e API Blueprint
53
Documentazione
54
Swagger
JSON Schema
JSON ReferenceJSON Pointer
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
SDK
- (ripetiamolo) gli sviluppatori sono pigri ;)
- Forniamo quindi anche un Software Development Kit (SDK) per i linguaggi di programmazione più comuni
56
happy download
leanpub.com/thewebapinntux57
Q&A app, open source
github.com/BENTOSA/happy-ask-me
58
grazie!
www.bentosa.it
59
ONE MORE THING
60
Training Workshop
Growth Networking
www.bentosa.it
61