Mostrando entradas con la etiqueta webapi. Mostrar todas las entradas
Mostrando entradas con la etiqueta webapi. Mostrar todas las entradas
martes, 4 de febrero de 2020
Días atrás veíamos cómo utilizar Swashbuckle para generar automáticamente la descripción OpenAPI de APIs creadas con ASP.NET Core MVC y ponerlas a disposición de los consumidores en una ruta específica:
En este post vamos a ver un par de formas de sacar provecho de esta descripción:
- En primer lugar, usaremos Swagger UI para generar un sitio web interactivo de documentación y pruebas de nuestra API.
- Después, veremos cómo generar desde Visual Studio código cliente para acceder a la API.
martes, 28 de enero de 2020
La OpenAPI Specification (OAS) es un estándar abierto para la descripción de APIS REST promovido por la Iniciativa OpenAPI, un consorcio de compañías de primer nivel como Microsoft, Google, IBM, Paypal y otros.El objetivo de OpenAPI es conseguir una fórmula normalizada para describir las capacidades de un servicio REST, independientemente de los lenguajes o tecnologías con las que sea implementado. Esta descripción, normalmente especificada en formato JSON o YAML, permite a clientes (sean humanos o máquinas) descubrir servicios, comprender sus capacidades y conocer sus detalles de funcionamiento sin necesidad de tener acceso a su código fuente o documentación textual.
Esta especificación formal abre interesantes posibilidades, pues a partir de la definición estandarizada de servicios es posible, entre otros,
- disponer de herramientas de diseño y modelado de servicios,
- generar automáticamente páginas de documentación,
- generar automáticamente código cliente y servidor para dichos servicios para distintos, frameworks y lenguajes de programación,
- generar automáticamente código de testing y validaciones,
- o generar automáticamente mocks de servicios.
martes, 10 de julio de 2018
Los que lleváis tiempo programando APIs HTTP, ya sea con ASP.NET Core o con otras tecnologías, seguro que en muchas ocasiones habéis tenido que decidir cómo retornar al cliente, de forma más o menos normalizada, los errores producidos en el lado servidor.Lo habitual es echar mano de los status code de HTTP para indicar problemas en el proceso de una petición; de hecho, este protocolo dispone de un rico conjunto de códigos que en principio parecen cubrir todas nuestras necesidades.
Pero no siempre es así. Por ejemplo, si tenemos un servicio que permite a los clientes de una empresa formalizar un pedido a través de un API y una llamada a este servicio retorna un error HTTP 403 (forbidden), claramente estamos indicando que el solicitante no tiene permisos para hacer un pedido. Sin embargo, no tenemos una forma clara de indicar cuál es la causa de esta prohibición (¿quizás las credenciales no son correctas? ¿o quizás el cliente no tiene crédito en la empresa? ¿o puede ser que el administrador lo haya denegado expresamente?)
Para aportar más detalles sobre el problema, normalmente necesitaremos retornar en el cuerpo de la respuesta información extra usando estructuras o formatos personalizados, probablemente distintos de una aplicación a otra, y documentarlos apropiadamente para que los clientes puedan entenderlos. Y aquí es donde entra en juego el estándar “Problem details”.
martes, 3 de julio de 2018
Uno de los objetivos de ASP.NET Core ha sido siempre servir como infraestructura para la creación de servicios HTTP o APIs web, por lo que ya desde las primeras versiones se incluían funcionalidades específicamente diseñadas para facilitar esta tarea.ASP.NET Core 2.1 continúa profundizando en esa línea e incluye entre sus novedades el nuevo atributo
[ApiController], un decorador aplicable a controladores que los identifica como puntos de entrada de APIS, aplicando de forma automática una serie de convenciones bastante útiles a la hora de crear este tipo de componentes:[ApiController]
[Route("api/[controller]")]
public class ValuesController : ControllerBase
{
...
}
Fijaos que, a diferencia de ASP.NET Web API (.NET Framework), se ha optado por utilizar un atributo en lugar de emplear herencia (en aquél framework existía la clase ApiController).
A continuación veremos qué debemos tener en cuenta a la hora de aplicar este atributo a nuestros controladores y qué convenciones son las que estaremos asumiendo al utilizarlo.
martes, 6 de mayo de 2014
Pues continuamos profundizando en el sistema de rutado por atributos, o attribute routing, recientemente incluido en ASP.NET MVC y Web API. Si aún no conoces este mecanismo, te recomiendo que eches un vistazo a los dos artículos anteriores de la serie:Como vimos en el último post, en las rutas es posible incluir restricciones a los parámetros de entrada, de forma que si las condiciones especificadas no se cumplen, el sistema de routing descartará la regla y continuará buscando en la tabla de rutas una entrada que encaje con la petición entrante.
Así, la acción
Confirm() mostrada a continuación no será invocada ante peticiones como “/user/confirm/1234” o “/user/confirm/abcdef”:[Route("user/confirm/{pin:alpha:length(4}"] // 4 alphabet chars (a-z)
public ActionResult Confirm(string pin)
{
...
}
Y como también veíamos en el post anterior, MVC y Web API traen de serie un buen número de restricciones (alpha, bool, decimal, int, length, etc.) que podemos emplear directamente sobre nuestras rutas, pero, lo que es mejor, se trata nuevamente de un mecanismo extensible: podemos crear nuestras propias restricciones para attribute routing sin demasiado esfuerzo.
martes, 1 de abril de 2014
En la entrega anterior de la serie hicimos una pequeña introducción al attribute routing introducido en ASP.NET MVC 5 y Web API 2, explicando cómo podíamos activar esta característica y las reglas básicas para la definición de rutas sobre acciones y controladores de ambos frameworks.En esta ocasión vamos a ver cómo podemos incluir restricciones o constraints en dichas rutas, algo que podíamos conseguir también utilizando el rutado por convenciones pero de forma más farragosa y que ahora con attribute routing y otras mejoras incluidas en las últimas versiones de MVC y Web API se convierte en trivial.
Y ya de paso, repasaremos lo que son las restricciones de ruta y cómo podíamos usarlas en versiones anteriores de MVC y Web API, para que aquellos que aún no hayáis tenido oportunidad de trabajar con ellas.
martes, 25 de marzo de 2014
Como seguro sabéis, una de las novedades que acompañan a MVC 5 es la inclusión de un nuevo mecanismo para la definición de rutas llamado attribute routing, que básicamente consiste en acercar el registro de rutas a las acciones y controladores que las utilizan en lugar de definirlas en el tradicional y lejano RouteConfig.cs.
martes, 21 de enero de 2014
A través del formulario de contacto del blog, el amigo Carlos G. L. me enviaba una pregunta a raíz del último post de la serie sobre OWIN/Katana, relativo al uso de stage markers:(...) entonces, ¿esto quiere decir que podemos utilizar un middleware para dar soporte CORS a soluciones basadas en la primera versión de WebAPI o en MVC 4?Respuesta corta: sí. Siempre que se cumplan los requisitos de plataforma exigidos por Katana y los middlewares que queramos usar, nada impide hacerlo sobre aplicaciones con versiones anteriores de estos frameworks.
Y vamos con la respuesta larga…
martes, 16 de abril de 2013
Muchos ya sabréis que hace unos meses publicaron desde Microsoft un póster que describe muy detalladamente el ciclo de vida de una petición en ASP.NET Web API. En su momento lo referencié desde una entrada de la serie enlaces interesantes, pero últimamente he podido comprobar que aún no es lo suficientemente conocido, y desde luego bien vale la pena dedicarle un post en exclusiva.
Se trata de un documento fundamental para comprender qué es lo que ocurre desde que llega al servidor una petición a un servicio Web API hasta que la respuesta es enviada de vuelta al cliente. En él encontraréis reflejados aspectos tan interesantes como la ubicación de los delegating handlers en el pipeline, la creación de controladores, selección de acciones, filtros de acción, binding, media type formatters, y otros muchos, conociendo qué puntos del framework son extensibles por diseño.
Desde el sitio de descargas de Microsoft podéis obtenerlo en formato PDF.
Realmente imprescindible.
Publicado en Variable not found.
Se trata de un documento fundamental para comprender qué es lo que ocurre desde que llega al servidor una petición a un servicio Web API hasta que la respuesta es enviada de vuelta al cliente. En él encontraréis reflejados aspectos tan interesantes como la ubicación de los delegating handlers en el pipeline, la creación de controladores, selección de acciones, filtros de acción, binding, media type formatters, y otros muchos, conociendo qué puntos del framework son extensibles por diseño.
Desde el sitio de descargas de Microsoft podéis obtenerlo en formato PDF.
Realmente imprescindible.
Publicado en Variable not found.
martes, 11 de diciembre de 2012
Cuando trabajábamos con los Servicios Web de toda la vida, las herramientas de desarrollo incluían sistemas para generar la documentación básica de los servicios que implementábamos. El estándar WSDL (Web Services Description Language), era un lenguaje basado en XML que permitía describir las funcionalidades de un servicio web aportando gran cantidad de detalles sobre las operaciones, tipos de datos, o direcciones de acceso a las mismas.Gracias a esto, los desarrolladores podíamos conectarnos fácilmente a un servicio para consultar sus especificaciones técnicas, o incluso generar de forma automática código cliente o proxies que facilitaran el acceso remoto a las funciones publicadas en la red.
Y para los que venimos de esos tiempos, una de las primeras dudas que surgen al comenzar a trabajar con WebAPI es si existe algo similar. Y la respuesta es sí, pero no ;-P
miércoles, 28 de marzo de 2012
¿Ein? ¿Pero no lo eran ya? Bueno, sí… pero no en toda la amplitud que puede ofrecer este término.
El progresivo acercamiento de ASP.NET al mundo del open source es algo que llevamos observando bastante tiempo. Desde hace unos años es posible acceder al código fuente de muchos productos, y también hemos visto cómo determinados proyectos puramente libres como jQuery eran incluidos con todos los honores en el conjunto de tecnologías de desarrollo oficiales de Microsoft. Ahora vamos un paso más allá.
El progresivo acercamiento de ASP.NET al mundo del open source es algo que llevamos observando bastante tiempo. Desde hace unos años es posible acceder al código fuente de muchos productos, y también hemos visto cómo determinados proyectos puramente libres como jQuery eran incluidos con todos los honores en el conjunto de tecnologías de desarrollo oficiales de Microsoft. Ahora vamos un paso más allá.
