The document discusses RESTful APIs and ASP.NET Core. It begins by asking why RESTful APIs are needed and defines RESTful as being represented by URIs, HTTP methods, and hypermedia. It covers the six constraints of RESTful design including being client-server, having a uniform interface, being stateless, cacheable, using a layered system, and optionally having code on demand. It provides examples of RESTful routing in ASP.NET Core and adding support for XML, versioning, and HATEOAS. Finally, it emphasizes that not all APIs must be RESTful and to design with clients in mind rather than forcing RESTful implementation.

1. Aplicaciones
RestFul con
Asp.net Core
Germán Küber
Software Architect
http://germankuber.com.ar
@germankuber
@netbaires

2. 1. ¿Por qué la necesidad de RESTFull?
2. ¿Qué es RESTFull?
3. Los 6 conceptos de RESTFull
4. Como implementar RESTFull en Asp.net Core
5. Conclusión
¿Qué vamos a ver?

3. Las 8 Falacias de la Computación Distribuida
1. La red es confiable
2. La latencia es cero, la latencia no es problema
3. El ancho de banda es infinito
4. La red es segura
5. La topología no cambia
6. Hay uno y sólo un administrador
7. El coste de transporte es cero
8. La red es homogénea http://www.rgoarchitects.com/Files/fallacies.pdf

4. API
Application Programming Interface

5. REST
Representational State Transfer

6. ¿Qué no es REST?
• RPC
• SOAP and WSDL
• HTTP
• URIs

7. ¿Qué no es REST?
/getAllUsers
/getUserById?id=3
/getUserWithProfile?id=4&json=true
/updateProfile?name=harry
/deleteUserByName?name=jhon

8. ¿Qué SI es REST?
/users
/users/3
/users/3/profiles
/users?email=example@mail.com
/users/3/profiles/permissions

9. Las 7 propiedades de RESTFull
1. Rendimiento
2. Escalabilidad
3. Simplicidad
4. Modificabilidad
5. Visibilidad
6. Portabilidad
7. Confiabilidad
https://en.wikipedia.org/wiki/Representational_state_transfer#Architectural_properties

10. 6 constraints
1. Client – Server
2. Uniform Interface
3. Statelessness
4. Cacheable
5. Layered System
6. Code on Demand (opcional)

11. Client - Server
Cliente y servidor están separados
(Cliente y servidor pueden evolucionar por separado)

12. dotnet new webapi -n NetConf-Demo>
> dotnet run

13. dotnet add package Swashbuckle.AspNetCore
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
Startup.cs
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.UseMvc();
}
>

14. http://localhost:5000/swagger/

15. Uniform Interface
API y los consumidores comparten una sola interfaz,
técnica: URI, Method, Media Type

16. GET
/users
/users?name=test
/users/1
/users/4/comments
POST
/users
{…}
/comments
{…}
PUT
/users/3
{…}
DELETE
/users/3
/users/3/comments
/users/4/commetns/3

17. [HttpGet("{id}")]
public User Get(int id)
[HttpGet("{id}/comments")]
public User Get(int id)
[HttpGet("{id:int}/comments/{commentId:int}")]
public List<Comment> Get(int id,int commentId)
[HttpPost]
public void Post([FromBody]string value)
[HttpPut("{id}")]
public void Put(int id, [FromBody]string value)
Microsoft.AspNetCore.Mvc

18. [HttpGet("")]
public IEnumerable<User> Get([FromQuery]int pageIndex = 1,
[FromQuery]int pageSize = 10)
/api/users?pageIndex=4&pageSize=5
{
"results": [ {author}, {author}, …],
"metadata": {
"previousPage": "/api/users?pageIndex=03&pageSize=45",
"nextPage": "/api/users?pageIndex=05&pageSize=45"
}
}

19. dotnet add package Microsoft.AspNetCore.Mvc.Versioning
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddApiVersioning(options =>
{
options.ReportApiVersions = true;
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
});
}
Startup.cs
>

20. ApiVersion("1.0")]
[Route("api/users")]
public class UsersController : Controller
[ApiVersion("2.0")]
[ApiVersion("3.0")]
[Route("api/v{ver:apiVersion}/users")]
public class UsersV2Controller : Controller
{
[HttpGet, MapToApiVersion("3.0")]
public IActionResult GetV3() => Content("Version 3");
[HttpGet, MapToApiVersion("2.0")]
public IActionResult GetV2() => Content("Version 2");
}
[ApiVersion("5.0", Deprecated = true)]
[Route("api/v{ver:apiVersion}/users")]
public class UsersV1Controller : Controller
Microsoft.AspNetCore.Mvc.Versioning

21. > dotnet add package Microsoft.AspNetCore.Mvc.Formatters.Xml
Startup.cs
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(options =>
{
options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
});
}
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(options =>
{
options.OutputFormatters.RemoveType<TextOutputFormatter>();
options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});
}

22. Statelessness
Estado contenido dentro de la propia solicitud

23. > dotnet add package RiskFirst.Hateoas
services.AddLinks(config =>
{
config.AddPolicy<User>(policy =>
{
policy.RequireSelfLink()
.RequireRoutedLink("all", "GetAllModelsRoute")
.RequireRoutedLink("delete", "DeleteModelRoute",
x => new { id = x.Id });
});
});
public UsersController(ILinksService linksService)
Startup.cs
UsersController.cs

24. public UsersController(ILinksService linksService)
UsersController.cs
[HttpGet("{id}", Name = "GetModelRoute")]
public async Task<User> GetMyModel(int id)
{
var model = await userRepository.GetById(id);
await _linksService.AddLinksAsync(user);
return user;
}
RiskFirst.Hateoas

25. Startup.cs
UsersController.cs
{
"id": 1234,
"name": "Bob",
"userName": "SurT",
"_links": [
{ "rel": "self", "href": "/people/1234” },
{
"rel": "update-person",
"href": "/people/1234",
"method": "PUT"
},
{
"rel": "delete-person",
"href": "/people/1234",
"method": "DELETE"
}
]
}
Hateoas

26. Cacheable
Cada respuesta/mensaje debe indicar explícitamente
si se puede almacenar en caché o no.

27. > dotnet add package Marvin.Cache.Headers --version 1.0.0
public void ConfigureServices(IServiceCollection services)
{
services.AddHttpCacheHeaders();
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseHttpCacheHeaders();
app.UseMvc();
}
Startup.cs

28. dotnet add package --version 1.0.0
Response Header
{
"last-modified": "Sun, 08 Oct 2017 15:00:58 GMT",
"etag": "949E486E372B3C6BA94E7D80AA67E512",
"cache-control": "public,max-age=60",
"expires": "Sun, 08 Oct 2017 15:01:58 GMT"
}
Marvin.Cache.Headers
Request Header

29. Cliente 1 Cliente 2 API
G E T api/authors/{id}
G E T api/authors/{id}
PUT api/authors/{id}
Concurrencia
PUT api/authors/{id}

30. Cliente 1 Cliente 2 API
Concurrencia en RESTFull
G E T api/authors/{id}
PUT api/authors/{id}
If-Match: “123456789”
2 0 0 Ok, ETag: “123456789”
G E T api/authors/{id}
200/204, ETag: “987654321”
PUT api/authors/{id}
If-Match: “123456789”
412 Precondition failed
2 0 0 Ok, ETag: “123456789”

31. Layered System
El cliente no puede saber a qué capa está conectado

32. FIREWALL GATEWAY
LOAD
BALANCER
CLIENTE
Layered System

33. Code on Demand
(optional)
Servidor puede extender la funcionalidad del cliente

34. RESUMEN
• No toda api es una api RESTFull
• Debemos diseñar siempre pensando en nuestros clientes
• No debemos forzar la implementación de RESTFull
• RESTFull prepara nuestras API para el futuro

35. Recursos
Microsoft REST API Guidelines
https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md
Asp.net Core
https://docs.microsoft.com/en-us/aspnet/core/
Roy T. Fielding's dissertation
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

36. Gracias
Germán Küber
Software Architect
http://germankuber.com.ar
@germankuber