presenta Tutti per uno e Swagger per tutti! Nicolò Carandini MVP Windows Development n.carandini@mahiz.it @TPCWare www.wpc2015.it info@wpc2015.it - +39 02 365738.11 - #wpc15it 1
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 www.wpc2015.it info@wpc2015.it - +39 02 365738.11 2
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? www.wpc2015.it info@wpc2015.it - +39 02 365738.11 3
Iniziamo dal World Wide Web www.wpc2015.it info@wpc2015.it - +39 02 365738.11 4
Il Web usa HTTP e HTML www.wpc2015.it info@wpc2015.it - +39 02 365738.11 5
HTTP (Hypertext Transfer Protocol) www.wpc2015.it info@wpc2015.it - +39 02 365738.11 6
Uniform Resource Locator www.wpc2015.it info@wpc2015.it - +39 02 365738.11 7
Web App Vs. Web Service www.wpc2015.it info@wpc2015.it - +39 02 365738.11 8
Quiz Time Lo conoscete? www.wpc2015.it info@wpc2015.it - +39 02 365738.11 9
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". www.wpc2015.it info@wpc2015.it - +39 02 365738.11 10
REpresentational State Transfer Client Server Uniform interface Stateless Cacheable Layered system www.wpc2015.it info@wpc2015.it - +39 02 365738.11 11
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 www.wpc2015.it info@wpc2015.it - +39 02 365738.11 12
REST: Stateless www.wpc2015.it info@wpc2015.it - +39 02 365738.11 13
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 14
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 15
TaskTimer: il modello www.wpc2015.it info@wpc2015.it - +39 02 365738.11 16
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 www.wpc2015.it info@wpc2015.it - +39 02 365738.11 17
UsersController ASP.NET WebAPI: Routing La chiamata REST viene instradata al metodo del controller che implementa il percorso contenuto nella URL: GET http://tasktimer.com/api/v1/users www.wpc2015.it info@wpc2015.it - +39 02 365738.11 18
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 http://tasktimer.com/api/v1/customers/123 { } CompanyName : "Fiat" www.wpc2015.it info@wpc2015.it - +39 02 365738.11 19
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 20
Documentazione delle API inizialmente viene fatta poi diventa incompleta e alla fine è spesso inesatta www.wpc2015.it info@wpc2015.it - +39 02 365738.11 21
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 www.wpc2015.it info@wpc2015.it - +39 02 365738.11 22
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 23
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 24
Includere la documentazione XML del codice 1. Abilitare la generazione della documentazione XML: 2. Abilitare l uso della documentazione XML in Swagger UI: www.wpc2015.it info@wpc2015.it - +39 02 365738.11 25
Demo: Swagger e Swagger UI con Swashbuckle www.wpc2015.it info@wpc2015.it - +39 02 365738.11 - #wpc15it 26
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 27
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 28
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 29
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. www.wpc2015.it info@wpc2015.it - +39 02 365738.11 30
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: www.wpc2015.it info@wpc2015.it - +39 02 365738.11 31
Swagger per tutti SwashBuckle AutoREST HTTP Rest Comunication www.wpc2015.it info@wpc2015.it - +39 02 365738.11 32
Demo: AutoRest Code generation Client App www.wpc2015.it info@wpc2015.it - +39 02 365738.11 - #wpc15it 33
Azure App Service www.wpc2015.it info@wpc2015.it - +39 02 365738.11 34
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 www.wpc2015.it info@wpc2015.it - +39 02 365738.11 35
Demo: Custom API App www.wpc2015.it info@wpc2015.it - +39 02 365738.11 36
Demo: Logic App www.wpc2015.it info@wpc2015.it - +39 02 365738.11 37
Question Time www.wpc2015.it info@wpc2015.it - +39 02 365738.11 - #wpc15it 38
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 www.wpc2015.it info@wpc2015.it - +39 02 365738.11 - #wpc15it 39
Articoli Swagger and ASP.NET Web API - Part I: Adding Swagger to Web API project www.wmpratt.com/swagger-and-asp-net-web-api-part-1 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 www.windowsazureitalia.com/articoli/windows-azure/introduzione-azure-logic-apps.aspx 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 www.wpc2015.it info@wpc2015.it - +39 02 365738.11 - #wpc15it 40
OverNet Education info@overneteducation.it www.overneteducation.it Tel. 02 365738 Contatti OverNet Education @overnete www.facebook.com/overneteducation www.linkedin.com/company/overnet-solutions www.wpc2015.it www.wpc2015.it info@wpc2015.it - +39 02 365738.11 - #wpc15it 41