Anche voi siete in piena "APIFICATION"? Riccardo ci svela tutti i segreti per rilasciare API di successo. #apistrategy Per ulteriori informazioni scrivi a wso2.sales@profesia.it

2. Iscriviti al gruppo Linkedin WSO2 Italia per entrare nella community italiana,
conoscere la tecnologia WSO2 e condividere strategie di integrazione e use cases

3. Cos’è una API “di successo”?
● Production grade: progettata per essere sfruttata in maniera
intensiva e frequente e durevole nel tempo
● API non è il servizio: è il biglietto da visita con la quale si
presenta la propria applicazione o parte di essa
● È studiata per essere conforme all'architettura
● La sua dissemination deve essere in grado di raggiungere tutte
le figure professionali
● Deve essere adeguata per essere utilizzabile su strumenti di
collaborazione

4. Architetture e APIs
● Non si sceglie mai lo stile architetturale del proprio sistema a valle della
scelta tecnologica, bensì il contrario!
● Il primo passo per definire una buona architettura è la comprensione
della data exchange tra i sistemi
● Lo sviluppo di una buona API è alla base della data exchange: l’API è
un contratto a supporto della data exchange
● L’API è prima di tutto un tema di natura architetturale

5. Architetture e APIs
● Uno stile architetturale è determinato dalle proprietà
dell’architettura
● Le proprietà dell’architettura sono la conseguenza
dei vincoli imposti per l’architettura (vincoli di
business, tecnici o, anche, sociali)
● Come ci sono diversi stili architetturali, esistono
diversi stili di APIs
● Non esiste un stile architetturale universalmente
valido per tutte le esigenze…
...e per le APIs?

6. Tipologie di APIs
API Timeline
< 1999
1991: CORBA
1993: RDA
1998: XML-RPC
SOAP
1999
2000
REST
2015
GRAPHQL
2005: JSON-RPC
2007: ODATA
2005-2007
gRPC
2016

7. Tipologie di APIs
API Styles
W
E
B
A
P
I
s
RPC
APIs STREAM
ING
APIs
QUERY APIs
F
L
A
T
F
I
L
E
S
A
P
I
s

8. Tipologie di APIs
SOAP vs REST vs GraphQL vs gRPC
SOAP REST GraphQL gRPC
HTTP, SMTP, FTP,...
Precursore di successo delle web
APIs
Numerose specifiche di I/O
Natura prolissa XML + namespaces
+ text-based = messaggi
voluminosi -> minore efficienza
HTTP
Semplice da interpretare
Produttività pressoché immediata
Request/response in HTTP 1.1:
meno efficiente (vedi HTTP/2)
Struttura dati della response
immutabile
Adeguato sia per server-to-server
che client-to-server (soprattutto per
state machine/CRUD)
Flessibile
Perfetto per comunicazioni
client-to-server
Adatto per reportistica
Non efficiente per comunicazioni
server-to-server
Deve prevedere un cambio di
mentalità
HTTP/2
Binario (non text-based): protobuf
Bi-direzionale su singola
connessione (streaming)
Perfetto per comunicazioni
server-to-server
Non adeguato per comunicazioni
client-to-server (non tutte le
applicazioni supportano HTTP/2)
Necessario coordinamento in caso
di cambiamento della struttura del
.protobuf

9. Tipologie di API
...e quindi?
“THERE IS NO UNIVERSAL BEST API STYLE. THERE IS ALWAYS A BEST API
STYLE FOR YOUR PROBLEM”
Per un'azienda che è avversa al rischio e vuole utilizzare un formato collaudato oppure preferisce
uniformare un unico stile di API per tutte le comunicazioni, REST è probabilmente più adatto per
soddisfare la necessità
Se la stessa società ha bisogno, per una propria webapp, di fornire la massima flessibilità per supportare
interazioni tra client e server sia sincrone che asincrone o necessita di effettuare parecchie interazioni
query-style su dati distribuiti, GraphQL è da tenere in considerazione
Se si necessita di implementare una data exchange più efficiente e real-time, sia mono-direzionale che
bi-direzionale (streaming), gRPC è la soluzione più opportuna

10. Approccio allo sviluppo di APIs:
Design-first vs Code-first
Design API Document API Code
Code Design API Document API
● Adeguato per approccio sia agile che
waterfall
● Continuo scambio con gli stakeholders/utenti
finali PRIMA di sviluppare codice
● API parlanti per qualunque attore
● Comunicazione e specifiche chiare
● Adeguato per API da esporre pubblicamente
● Non adeguato per approccio agile
● L’API rispecchia il codice: costi per riscrittura
del codice se API non adeguata alle
aspettative
● Bassa standardizzazione
● Adeguato per approccio speed to delivery e
per applicazioni legacy
● Scambio con gli stakeholders macchinoso

11. REST API Standardization
Naming convention
Business terms
(vedi approccio Domain-Driven: ubiquitous
language). Termini chiari e facilmente
comprensibili
KO: controller-impl, Dao, Dto, main, RestRequest, RestResponse,...
OK: valid-orders (or ValidOrders), Cart, Payments, Fault, Result,...
Oggetto di business (o main object)
compliant
Nome degli elementi compliant allo scopo
dell’API
GET /order-details: $.OrderDetails.List[]
Resources al plurale KO: GET /order (senza ulteriori parametri: chi legge lo swagger riesce a capire se
l’api restituirà un singolo ordine or restituisce più ordini?)
OK: GET /orders + GET /orders/1 (si sa, a colpo d’occhio, che nel primo caso
restituisce tutti gli ordini, nel secondo solo uno)

12. REST API Standardization
Structure convention
Hierarchical URI
per identificare il contesto (vedi approccio
Domain-Driven: bounded context)
/sales/order/item
/finance/invoice/item
Evitare ridondanze /sales/sales-order/validated/valid-orders
Evitare ovvietà /api/sales/resource/orders
Non usare HTTP verbs in URI KO: GET /orders/get or POST /orders/doUpsert
OK: GET /orders (per retrieve) and POST /orders (per upsert)

13. REST API Standardization
Structure convention
Nested resources
Approccio deprecato. Sfruttare url parameters
invece delle risorse innestate per creare relazioni
KO: GET /orders/customer/999/invoice/12345
OK: GET /orders?customerId=999&invoiceId=12345
Abuso safe HTTP methods Usare GET per fare una DELETE
Error Handling ● Sfruttare (adeguatamente) HTTP error codes: 5xx per errori server-side,
4xx per errori client-side (con un 400 bad request, il client non DOVREBBE
ritentare la chiamata)
● Strutture di Fault univoche e parlanti
{
"fault" : {
"errorCode" : "ERR-00001",
"errorMsg" : "The combination of given parameter is not correct",
"errorClass" : "ParameterException",
"errorDetails" : { "error": "Magnitude XYZ is not correct for the given pod 123"}
}
}

14. REST API Standardization
Alcuni suggerimenti
● Sfruttare sistemi di versioning delle API
● Appoggiarsi a tool per la definizione di regole di
standardizzazione (es: SwaggerHub*)
● Sfruttare strumenti di collaboration per evolvere le API
*https://swagger.io/tools/swaggerhub/

15. API Products
● E’ un meccanismo di bundling delle API
● Definire un bundle di risorse selezionate da una o
più API così da essere esposte come una API
separata
● Creare diverse API come combinazione di quelle già
esistenti
● Fornire un prodotto (API) su misura per particolari
stakeholders
https://apim.docs.wso2.com/en/latest/design/create-api-product/api-product-overview/

16. Throttling e Rate Limit
● Non confondere throttling/rate limit policies con resiliency
patterns
● Throttling/Rate limit: limita il numero di risorse utilizzabili da un
client (o da una sua componente o servizio) così che il proprio
servizio continui a funzionare soddisfando le SLA anche in
situazioni di pieno carico
● Resiliency: è la capacità di un sistema di riprendere senza
impatti sui consumers la sua funzionalità a seguito di fallimenti

17. Throttling e Rate Limit
● Rate limit: impone un numero massimo di richieste che possono
giungere all’API in una determinata finestra di tempo. L’API rifiuta
le richieste che superano quel limite
● Throttling: accoda quelle richieste giunte all’API che superano un
determinato limite ed eventualmente le processa nella finestra
temporale successiva. L’API può rifiutare le richieste dopo un
certo numero di tentativi
● Rate limit e throttling limitano entrambi l’accesso all’API: il primo
impone un limite fisso di accesso, il secondo controlla le richieste
all’API livellando i picchi di traffico

18. Throttling e Rate Limit
WSO2 Throttling/Rate Limit Policies
Application-level: Per-token quota
Applied to users of the applications
Applied to a single user (token) accessing all APIs of the
application (es: 10perMin)
Subscription-level: Subscription tiers
Applied to applications that consume that API
Applied across all users of the application.
A shared quota among all users of an application that access
that API (es: 10KperMin)
Subscription-level: API published
Applied to single API
● Quota Limits: Request count (es: 5KperMin) or Request
Bandwith (es: 500 MBperHour)
● Burst Control: Spike Arrest Policy
API-level
Applied to API and API resources
● Limit on Resource (es: 2KperMin)
● Request Filtering (IP address/Address range, HTTP
Request Headers, JWT Claims, Query params)
Maximum backend throughput
Applied to full backend system/service
In TPS

19. Throttling e Rate Limit
WSO2 Throttling/Rate Limit Policies

20. Monitoring
● Monitorare il traffico e il lineage della propria API
● API è il biglietto da visita dell’azienda (o parte di
essa): monitorare l’API è monitorare l’azienda
● Capire chi chiama cosa e come
● Avere una visione near-realtime dell’andamento di
un’azienda api-centric

21. Summary
● API è un tema di natura architetturale
● Non esiste uno stile di API valido per tutte le
esigenze
● Design-first
● Standardizzazione e naming convention
● Garantire l’affidabilità delle proprie API
● Combinare le soluzioni per un’offerta su misura
● Monitoring

22. Q&A?

23. GRAZIE!!!
Prossimo appuntamento:

25. Contatti
DOVE SIAMO
Milano - Torino - Padova - Roma
TELEFONO
Torino +39-011-0120371
EMAIL
wso2.sales@profesia.it
@