Construyendo una API RESTful con ASP.NET Core 2.0

Transcript

3. ¿Qué es una API? Cualquier interfaz bien definida que especifique los servicios que un componente, módulo o aplicación ofrece a otras piezas de software.
4. ¿Qué es una API? Es una interfaz de usuario para programadores
5. Web APIs
6. REST vs SOAP
7. REST vs SOAP RPC
8. REST vs RPC
9. Web APIs
10. ¿Qué es REST? REpresentational State Transfer Es un estilo de arquitectura para desarrollar sistemas distribuidos
11. Restricciones REST
12. Interfaz uniforme Interfaz uniforme
13. Interfaz uniforme Interfaz uniforme
14. HATEOAS HATEOAS Hypermedia as the Engine of Application State
15. Modelo de madurez de Richardson GLORIA DE REST
16. Nivel 0: The SWAMP of POX •  Única URI de entrada •  Un solo verbo HTTP •  XML-RPC / SOAP / POX Crear un cliente POST http://localhost/api Obtener un cliente POST http://localhost/api
17. NIVEL 1: Recursos •  Cada recursos tiene su URI •  Un solo verbo HTTP (normalmente GET o POST) •  Los verbos no tienen significado Crear un cliente POST http://localhost/api/clientes Obtener un coche POST http://localhost/api/coches/{id}
18. NIVEL 2: Verbos HTTP •  Varias URI, utilizando múltiples verbos •  Uso correcto de los códigos de respuesta •  Expone estado, no el comportamiento Crear un cliente POST http://localhost/api/clientes 201 Created (Cliente) Obtener un cliente GET http://localhost/api/clientes/{id} 200 Accepted (Cliente)
19. Verbos HTTP CRUD* SEGURO IDEMPOTENTE GET READ SI SI HEAD SI SI POST CREATE NO NO PUT UPDATE/ REPLACE NO SI DELETE DELETE NO SI PATCH UPDATE/ MODIFY NO NO OPTIONS - SI SI
20. Códigos de estado HTTP Peticiones Correctas Errores del cliente Errores del servidor 200 OK 400 Bad Request 500 Internal Server Error 201 Created 401 Unauthorized 204 No Content 403 Forbidden 404 Not Found 405 Method Not Allowed 410 Gone 415 Unsupported Media Type 422 Unprocessable Entity 429 Too Many Requests https://httpstatuses.com/
21. NIVEL 3: Controles Hypermedia •  Los recursos son autodescriptivos •  HATEOAS •  Expone estado y comportamiento Obtener un cliente GET http://localhost/api/clientes/3 200 Accepted (Cliente + enlaces) “links”: [ { “href”: http://localhost/api/clientes/3, “rel”: “self”, “method” : “GET” }, { “href”: http://localhost/api/clientes/3, “rel”: “delete_cliente”, “method” : “DELETE” } ]
22. ¿Es nuestra API RESTful? Según Roy Fielding… una API sólo puede considerarse RESTful cuando se ajusta a todas las restricciones de REST
23. ¿Es nuestra API RESTful?
25. ASP.NET Core .NET Framework .NET Core Platform for .NET applications on Windows Cross-platform, modular libraries & runtime optimized for server and cloud workloads
27. Creando un proyecto ASP.NET Core Instalar .NET Core 2.0 desde http://dot.net/core
28. Configuración de la aplicación Inicialización del host Configuración servicios (DI) Configuración Middlewares
29. Middleware Request Response
31. Definición del API Operación Verbo Recurso Listado de clientes GET /clientes/ Consulta de un cliente GET /clientes/{id} Crear nuevo cliente POST /clientes/ Actualizar información de un cliente PUT/PATCH /clientes/{id} Eliminar un cliente DELETE /clientes/{id} Listado de presupuestos de un cliente GET /clientes/{id}/presupuestos
32. Consulta de un recurso GET /clientes/{id} Resultado Cuerpo Código de respuesta Cliente encontrado Cliente 200 Accepted Cliente no encontrado - 404 Not Found Respuesta
33. Consulta de colecciones GET /clientes/ Resultado Cuerpo Código de respuesta Hay clientes Listado de clientes 200 Accepted No hay clientes Listado vacío 200 Accepted Respuesta
34. Creando un recurso POST /clientes Resultado Cuerpo Código de respuesta Cliente creado Cliente 201 Created Cuerpo incorrecto Mensaje de error 400 Bad Request Errores de validación Mensaje de error 422 Unprocessable Entity Error de servidor Mensaje de error 500 Internal Server Error Respuesta { “nombre”: “Carlos”, “apellidos”: “Saez Dorado”, “telefono”: “123456789”, “esVip”: true } También es posible utilizar PUT para crear nuevos recursos [Location Header]
35. Actualizando un recurso PUT /clientes/{id} { “nombre”: “Carlos”, “apellidos”: “Saez Dorado”, “telefono”: “123456789”, “esVip”: true } Resultado Cuerpo Código de respuesta Cliente actualizado Cliente 200 Accepted Cliente no encontrado 404 Not Found Cuerpo incorrecto Mensaje de error 400 Bad Request Errores de validación Mensaje de error 422 Unprocessable Entity Error de servidor Mensaje de error 500 Internal Server Error
36. Actualizando un recurso parcialmente PATCH /clientes/{id} [ { "op": "replace", "path": "/nombre", "value": "Jose" } ] Resultado Cuerpo Código de respuesta Cliente actualizado Cliente 200 Accepted Cliente no encontrado 404 Not Found Cuerpo incorrecto Mensaje de error 400 Bad Request Errores de validación Mensaje de error 422 Unprocessable Entity Error de servidor Mensaje de error 500 Internal Server Error JSON PATCH
37. Borrando un recurso DELETE /clientes/{id} Resultado Cuerpo Código de respuesta Cliente borrado - 204 No Content Cliente no encontrado - 404 Not Found Error de servidor Mensaje de error 500 Internal Server Error Respuesta
38. Relaciones GET /clientes/{id}/presupuestos POST /clientes/{id}/presupuestos DELETE /clientes/{id}/presupuestos/ {prespuestoId}
39. Filtrado, paginación y ordenación GET /clientes?esVip=true GET /clientes?orderBy=name GET /clientes?page=2 GET /clientes?query=“Carlos” Si utilizamos demasiados parámetros debemos valorar usar POST Incluimos información de la paginación en el body y en el Link Header
40. Otras acciones GET /clientes/favoritos POST /clientes/{idCliente}/presupuestos/ {id}/aprobado POST /busqueda
41. Embeded + Objetos parciales GET /clientes?fields=id,nombre GET /clientes?embed=presupesto.id, prespuesto.importe GET /clientes?fileds=id,nombre &embed=presupesto.id, prespuesto.importe
42. Formatos Favorecer JSON el cual ya se aplica por defecto public void ConfigureServices(IServiceCollection services) { services.AddMvc(options => { options.OutputFormatters.Add(new XmlSerializerOutputFormatter()); options.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter()); }); } Otros formatos (p.ej. XML)
43. Hypermedia •  JSON-LD •  HAL •  JSON API •  COLLECTION+JSON •  SIREN Representación en HAL
44. Shared vocabularies
45. Documentación + Schema
46. Documentación + Schema public void Configure(IApplicationBuilder app, IHostingEnvironment env) { services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Title = “API", Version = "v1" }); });} public void Configure(IApplicationBuilder app) { app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1”);} ); }
47. Compresión gzip Mejor utilizar la del servidor (IIS, Apache…) public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.Configure<GzipCompressionProviderOptions>(options => options.Level = System.IO.Compression.CompressionLevel.Optimal); services.AddResponseCompression(); } public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseResponseCompression(); app.UseMvc(); }
48. Otros •  Seguridad •  API Keys, OAuth2, JWT… •  Rate limits •  SSL •  Autorización y autenticación (Status Code: 401, 403…) •  Caching •  Etag, Last Modified Since •  Versionado API •  URL, Headers, Media Type…
49. Libros recomendados
50. Referencias ProgrammableWeb https://www.programmableweb.com/ Richardson Maturity Model – Martin Fowler https://martinfowler.com/articles/richardsonMaturityModel.html Understanding RPC Vs REST For HTTP APIs - Phil Sturgeon https://www.smashingmagazine.com/2016/09/understanding-rest-and-rpc-for- http-apis/ A Response to REST is the new SOAP - Phil Sturgeon https://philsturgeon.uk/api/2017/12/18/rest-confusion-explained/ KNOW YOUR HTTP * WELL https://github.com/for-GET/know-your-http-well http-decision-diagram https://github.com/for-GET/http-decision-diagram
51. Referencias Tesis doctoral de Roy Fielding http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm Best Practices for Designing a Pragmatic RESTful API - Vinay Sahni http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api API Stylebook http://apistylebook.com/ REST APIs must be hypertext-driven - Roy Fielding http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven GraphQL ha muerto: Vivan las APIs REST con Hypermedia - Jorge Ferrer y Jose Manuel Navarro https://www.youtube.com/watch?v=ud1fWXACWm0 Open API Initiative https://www.openapis.org/
52. Referencias API Handyman https://apihandyman.io/ Documentación ASP .NET Core https://docs.microsoft.com/es-es/aspnet/core/ Fanie Reynders https://reynders.co/ ASP .NET Core Fundamentals – Carlos Landeras https://www.youtube.com/watch?v=xWqKA5T7QUA http://www.innovarioja.tv/index.php/video/ver/1792 Building a RESTful API with ASP .NET Core - Kevin Dockx (Pluralsight) https://www.pluralsight.com/courses/asp-dot-net-core-restful-api-building