Cerchiamo di capire cosa vuol dire creare delle API pubbliche. Cerchiamo di capire cosa offre ad oggi ASP.NET, e come utilizzare al meglio la tecnologia. L'intenzione è di andare in dettaglio su problematiche spesso sottovalutate: serve sempre ASP.NET Web API? E' meglio WCF? Quali problematiche possono capitare? Come faccio il versionamento? Quali oggetti/classi espongo? E la documentazione?

1. www.xedotnet.org
Andrea Dottor
Microsoft MVP ASP.NET
@dottor
Creare API pubbliche, come
evitare gli errori comuni

2. Chi sono
Andrea Dottor
Microsoft MVP ASP.NET
www.dottor.net
andrea@dottor.net
@dottor

3. intro
• Il capo ti chiama
• Nuovo progetto
• Usare servizi REST pubblici per recuperare i dati
• Ma non i soliti che usano tutti
• Te li fa cercare a te, perché vuole qualcosa di particolare
• Fatichi a trovarli
• Scopri come (non) sono fatti

4. Sarà capitato anche a voi
Di perdervi cercando la documentazione

5. O volervi buttare di sotto
quando vi hanno obbligato ad utilizzare quelle API
credits:40 Carati – Man on a Ledge

6. Evitiamo gli errori comuni
• Dove sbagliano sempre gli altri?
• Mancanza di documentazione
• API e/o DTO che cambiano senza preavviso
• Uso errato degli Http-Method
• Autenticazione (o altro) non standard
• …
• Etica della reciprocità:
• "Comportati con chi ti è inferiore come vorresti che si comportasse
con te chi ti è superiore." (Lucio Anneo Seneca)
• "Non fare a nessuno ciò che non piace a te." (Libro di Tobia)

7. Le API sono una tua vetrina
• Alcuni clienti conosceranno le tue API prima di
conoscere te
• La prima impressione è spesso quella che conta
• API poco (o per niente) documentate è una delle
prime motivazioni per far si che non vengano
utilizzate
• API troppo complesse…sono la seconda
motivazione per far si che non vengano utilizzate
• L'adozione di standard ne facilita l'uso

8. alcuni semplici consigli

9. Esponi dei DTO (Data Transfert Object)
• Non ritornare MAI gli oggetti di business o le classi
del model dell'Entity Framework (o simili)
• Modifiche fatte a questi oggetti possono ripercuotersi su
chi utilizza le API
• Cambio di tipo di una proprietà
• Cambio del nome di una proprietà
• Cancellazione di una proprietà
• Esponendo le proprie classi non si ha scelta su quali
proprietà far vedere o nascondere
• E' preferibile creare degli oggetti DTO studiati sulle
reali necessità di chi dovrà utilizzare i vostri servizi

10. DEMO
DTO

11. Action e HTTP Method
1. I metodi in GET non devono modificare i dati!
2. Non utilizzate (solo) i nomi delle action per
specificare cosa fa un metodo.
Es:
/getAllCars
/createNewCar
/deleteAllRedCars

12. Uso corretto degli HTTP Method
HTTP Verb CRUD Entire Collection (e.g. /customers) Specific Item (e.g. /customers/{id})
POST Create 201 (Created), 'Location' header with
link to /customers/{id} containing
new ID.
404 (Not Found), 409 (Conflict) if
resource already exists..
GET Read 200 (OK), list of customers. Use
pagination, sorting and filtering to
navigate big lists.
200 (OK), single customer. 404 (Not
Found), if ID not found or invalid.
PUT Update/Replace 404 (Not Found), unless you want to
update/replace every resource in the
entire collection.
200 (OK) or 204 (No Content). 404
(Not Found), if ID not found or
invalid.
PATCH Update/Modify 404 (Not Found), unless you want to
modify the collection itself.
200 (OK) or 204 (No Content). 404
(Not Found), if ID not found or
invalid.
DELETE Delete 404 (Not Found), unless you want to
delete the whole collection—not
often desirable.
200 (OK). 404 (Not Found), if ID not
found or invalid.

13. Uso corretto degli Status Code
2xx Success
• 200 OK
• 201 Created
• 204 No Content
4xx Client Error
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 409 Conflict
5xx Server Error
• 500 Internal Server Error

14. Uso corretto degli Status Code
• Ritornare un oggetto di tipo IHttpActionResult
• Ritornare un oggetto di tipo HttpResponseMessage
Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
if (film == null)
return NotFound();
http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/action-results

15. DEMO
HTTP Method e Status Code

16. CORS
• Ricordarsi di abilitare CORS se vogliamo che le API siano
utilizzabili da tutti
• Di default di browser bloccano le chiamate JavaScript
verso altri domini
• Come?
• Aggiungere pacchetto nuget: Microsoft.AspNet.WebApi.Cors
• Abilitarlo nel file WebApiConfig.cs
config.EnableCors(new EnableCorsAttribute("*", "*", "*"));
• (oppure) Aggiungere pacchetto nuget: Microsoft.Owin.Cors
• Abilitarlo nel file Startup.cs
app.UseCors(Microsoft.Owin.Cors.CorsOptions.AllowAll);

17. la parte noiosa
ma la più utile per chi deve manuntenere
o utilizzare le tue API

18. Versionamento
• Le API devono funzionare sempre
• Mai modificare i DTO in API pubbliche (utilizzate)
• Non modificare il tipo di una proprietà
• Mai modificare il nome di una proprietà
• Compreso purtroppo gli errori di ortografia
• Mai aggiungere o rimuovere proprietà
• E quindi?
• Versionare!
es: api/v1/prodotti
• Gli utilizzatori devono avere il tempo di migrare i propri
client verso la nuova versione

19. DEMO
versionamento

20. Documentazione
• Esporre delle API senza documentazione equivale
(quasi) a non avere delle API
• Cosa possiamo fare?
• Help Page
• Presente di default nei progetti ASP.NET Web API
• Swagger
• http://swagger.io/
• "Swagger is a simple yet powerful representation of your
RESTful API."
• Nuget: Install-Package Swashbuckle

21. Web API help page

22. Swagger

23. DEMO
documentazione

24. Testing
• MAI dare per scontato che una vostra modifica
funzioni
• Testare sempre le API prima di pubblicarle
• Evitate che sia il cliente a fare da tester
• Utilizzare un ambiente di pre-produzione (dove eseguire
i test)

25. postman
Per i pigri
• E' possibile far generare le collection per postman
• Semplifica/velocizza le operazione di testing

26. DEMO
postman

27. Chi sono
Andrea Dottor
Microsoft MVP ASP.NET
www.dottor.net
andrea@dottor.net
@dottor

28. Si ringrazia
L'evento di oggi è sponsorizzato da Andrea Agnoletto
https://www.linkedin.com/in/andreaagnoletto
speakers:

29. Feedback
http://goo.gl/forms/1SSdTxJbyT