Tutti per uno e Swagger per tutti!

Transcript

1 presenta Tutti per uno e Swagger per tutti! Nicolò Carandini MVP Windows Development [email protected] #wpc15it 1

2 Agenda Session Tuning Web Services e REST API Cos è Swagger e a cosa serve Documentazione delle API Tools di generazione Integrazione con Azure Web Services Q&A [email protected]

3 Session tuning Che differenza c è tra HTTP e HTML? Che differenza c è tra Web App e Web Service? Chi è Tim Berners-Lee? Cos è un servizio RESTful? [email protected]

4 Iniziamo dal World Wide Web

5 Il Web usa HTTP e HTML [email protected]

6 HTTP (Hypertext Transfer Protocol)

7 Uniform Resource Locator

8 Web App Vs. Web Service

9 Quiz Time Lo conoscete?

10 Roy Fielding Ha scritto una tesi di dottorato dal titolo: Architectural Styles and the Design of Network-based Software Architectures nella quale descrive una metodologia di scrittura dei servizi chiamata REST (Representational State Transfer). E uno dei principali autori delle specifiche dell HTTP (Hypertext Transfer Protocol) presso il W3C, dove ha lavorato con Tim Berners-Lee, meglio noto come "Father of Web". [email protected]

11 REpresentational State Transfer Client Server Uniform interface Stateless Cacheable Layered system

12 REST: Uniform Interface Utilizza i metodi HTTP (Get, Post, Put, Delete, ) per identificare l azione. Usa l URL (Uniform Resource Locator) per identificare la risorsa e i parametri Usa il body per i dati inviati o ricevuti, tipicamente in formato XML o JSON [email protected]

13 REST: Stateless

14 RESTful Web Service Un servizio web che utilizza i metodi HTTP e implementa i principi REST viene chiamato RESTful. ASP.NET WebAPI è un ottimo strumento di realizzazione di servizi RESTful. Attenzione: Non tutti i servizi web di tipo REST sono RESTful, si veda ad esempio il concetto di discoverability: If you are just using Rest for pretty urls mapped to CRUD operations that a consumer must have prior knowledge of and calls according to a well known contract, Roy Fielding would deem it not truly RESTful. [email protected]

15 Un esempio di Web Service: TaskTimer Per tener traccia del tempo impiegato dai vari developer per il completamento dei task. Basato sul cloud. Verticalmente scalabile. Utilizzabile da una pluralità di device. Facilmente integrabile

16 TaskTimer: il modello

17 TaskTimer: l architettura del progetto TaskTimer.WebAPI Servizio RESTful TaskTimer.Data Data access layer e Business logic TaskTimer.Core Modello ad oggetti e funzionalità di base [email protected]

18 UsersController ASP.NET WebAPI: Routing La chiamata REST viene instradata al metodo del controller che implementa il percorso contenuto nella URL: GET

19 DTO Controller Body ASP.NET WebAPI: Binding Una chiamata REST è formata dal Verbo e dal Path e dai dati eventualmente contenuti nei Query parameters, negli Headers e nel Body content. I dati vengono utilizzati per valorizzare i parametri del metodo associato atraverso un operazione di binding: PUT { } CompanyName : "Fiat" [email protected]

20 Web Service API L Application Programming Interface di un Web Service è definita da: L elenco delle richieste e delle relative possibili risposte Per ciascuna di esse la descrizione dei dati, che possono essere obbligatori o opzionali. Per quanto REST usi un meccanismo standard per effettuare le richieste e ricevere le risposte, occorre comunque avere a disposizione la documentazione delle API. [email protected]

21 Documentazione delle API inizialmente viene fatta poi diventa incompleta e alla fine è spesso inesatta [email protected]

22 Swagger Un linguaggio "JSON like" dedicato alla descrizione delle Web Service API. E una specifica Open Source, ed è diventato lo standard di fatto del mercato per la descrizione delle RESTful API. Intorno a questo "standard industriale" sono stati sviluppati molti tools di: Generazione automatica del documento Swagger Generazione della documentazione dell API Generazione del modello di classi DTO [email protected]

23 Swagger Ui Swagger UI è un insieme di template HTML, codice Javascript e CSS che generano dinamicamente una documentazione dell API fruibile da Web a partire da un documento Swagger. [email protected]

24 Swashbuckle Fornito tramite NuGet Package. Genera automaticamente il documento Swagger. Contiene al suo interno Swagger-ui. Genera lo schema dei dati delle API tramite Reflection. Consente la personalizzazione della documentazione Swagger generata e della Swagger UI. Utilizza e include automaticamente i commenti Xml del codice. Supporta la descrizione degli schemi ApiKey, Basic Auth and OAuth2, incluso il supporto UI per l Implicit OAuth2 flow. [email protected]

25 Includere la documentazione XML del codice 1. Abilitare la generazione della documentazione XML: 2. Abilitare l uso della documentazione XML in Swagger UI: [email protected]

26 Demo: Swagger e Swagger UI con Swashbuckle [email protected] #wpc15it 26

27 Utilizzare un Web Service RESTful Lato Client, un app usa HTTP per comunicare col servizio Web. I dati vengono scambiati attraverso la serializzazione / deserializzazione di classi DTO (Data Transfer Object), composte di sole proprietà, senza metodi. La generazione di questo modello "anemico" è noiosa e molto ripetitiva. Utilizzare le risposte serializzate per generare le classi DTO non è consigliabile. [email protected]

28 Un caso d uso: Azure e Swagger Qualunque operazione effettuabile su Azure è disponibile tramite un servizio web di tipo REST. Le API sono documentate con Swagger Un generatore automatico consente, a partire dalla documentazione scritta in Swagger, di produrre gli SDK di Azure nei vari linguaggi. Questo consente di avere tutti gli SDK sempre aggiornati all ultima versione delle Azure API. [email protected]

29 AutoRest E un tool per la generazione di librerie client per l accesso di servizi web RESTful. Come input viene utilizzato il documento che descrive le REST API scritto in formato Swagger. E in grado di generare librerie in diversi linguaggi, come C#, Javascript, ecc. [email protected]

30 Come utilizzare AutoRest per generare il codice cliente 1. Scaricare il generatore AutoRest con il NuGet Package Manager. 2. Creare una cartella di lavoro (ad esempio AutoRest). 3. Copiare dal package "autorest.x" il file "autorest.x.nupkg" e la cartella "Tools" nella cartella di lavoro. 4. Copiare nella cartella di lavoro il file swagger.json che descrive l API del servizio web 5. Sempre nella cartella di lavoro, creare il file batch di generazione: 6. Eseguire il file batch. [email protected]

31 Come utilizzare AutoRest nell app cliente 1. Scaricare l AutoRest client con il NuGet Package Manager. 2. Copiare il codice generato da AutoRest nel progetto. 3. Istanziare il servizio ed utilizzare le classi proxy per effettuare le richieste e gestire le risposte: [email protected]

32 Swagger per tutti SwashBuckle AutoREST HTTP Rest Comunication

33 Demo: AutoRest Code generation Client App #wpc15it 33

34 Azure App Service

35 Logic Apps Visual Editor per la creazione del flusso di elaborazione Un elevato numero di template disponibili Supporto per i più popolari servizi SaaS Può utilizzare custom API app fatte da noi BizTalk APIs for per scenari di integrazione evoluti [email protected]

36 Demo: Custom API App

37 Demo: Logic App

38 Question Time #wpc15it 38

39 Riferimenti Swagger swagger.io Swashbuckle github.com/domaindrivendev/swashbuckle AutoRest github.com/azure/autorest Azure Logic Apps azure.microsoft.com/en-us/documentation/services/app-service/logic #wpc15it 39

40 Articoli Swagger and ASP.NET Web API - Part I: Adding Swagger to Web API project Creating Service Contract with AutoRest, Swagger and HAL blog.kloud.com.au/2015/10/26/creating-service-contract-with-autorest-swagger-and-hal Introduzione alle Azure Logic App Azure Logic App with simple API App with inputs and outputs blogs.msdn.com/b/hosamshobak/archive/2015/03/31/logic-app-with-simple-api-app-with-inputs-and-outputs.aspx [email protected] #wpc15it 40

41 OverNet Education Tel Contatti OverNet #wpc15it 41