happy monday #1: the web api guidelines for happy developers

Happy Monday #1

The Web API guidelines for happy developers

Antonio Pintus & Federico Pinna

1

antonio@bentosa.it - fpinna@bentosa.it

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