7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
Advertisement
  1. Code
  2. ASP.NET

Desarrollando una API Web ASP.NET

Scroll to top
Read Time: 12 mins

Spanish (Español) translation by Ana Paulina Figueroa (you can also view the original English article)

La API Web ASP.NET es un framework para crear APIs web sobre el framework .NET que hace uso de HTTP. Ya que casi cualquier plataforma que puedas imaginar tiene una biblioteca HTTP, los servicios HTTP pueden ser consumidos por una amplia gama de clientes, incluyendo navegadores, dispositivos móviles y aplicaciones de escritorio tradicionales.

La API Web ASP.NET aprovecha los conceptos de HTTP y proporciona características tales como:

  • Diferentes tipos de Solicitud/Respuesta compatibles como HTML, JSON y archivos binarios (imagen/audio/video), y no solamente contenido XML como lo requiere SOAP.
  • Mapeo de acciones integrado en un controlador, basado en verbos HTTP (GET, POST, etc.).

Creando una API Web

Para crear una API Web usaremos Visual Studio. Si tienes Visual Studio 2012 o una versión posterior, entonces estás listo para comenzar con tu API Web.

Iniciando un nuevo proyecto

Desde el menú File (Archivo), selecciona New (Nuevo) y luego Project (Proyecto).

En el panel Templates (Plantillas) selecciona Installed Templates (Plantillas Instaladas) y expande el nodo Visual C#. Dentro de Visual C# selecciona Web. En la lista de plantillas para proyectos, selecciona ASP.NET Web Application (Aplicación Web ASP.NET). Asigna al proyecto el nombre de tu preferencia y haz clic en OK.

Starting a new project in Visual StudioStarting a new project in Visual StudioStarting a new project in Visual Studio

En la siguiente ventana se te presentará una lista de plantillas. Si bien puedes seleccionar cualquiera de las plantillas de la lista, ya que todas contendrán archivos DLL y las configuraciones requeridas para crear controladores API Web, vamos a seleccionar la plantilla Empy Project (Proyecto Vacío) para comenzar.

Choosing WEB API project templateChoosing WEB API project templateChoosing WEB API project template

Añadiendo un Controller (controlador)

En API Web, un controller (controlador) es un objeto que gestiona solicitudes HTTP. Vamos a añadir rápidamente un controlador para probar nuestra API Web.

En Solution Explorer (Explorador de Soluciones), haz clic con el botón derecho en la carpeta Controllers (Controladores). Selecciona Add (Añadir) y luego elige Controller (Controlador). Vamos a asignarle el nombre TestController al controlador y luego a seleccionar Empty API Controller (Controlador API Vacío) desde las opciones desplegables para la plantilla.

Adding first API ControllerAdding first API ControllerAdding first API Controller

Visual Studio creará nuestro controlador derivado de la clase ApiController. Vamos a añadir una función rápida aquí para probar nuestro proyecto API hospedándolo en IIS.

Hospedando en IIS

Ahora vamos a añadir nuestro servicio en IIS para poder acceder a él localmente. Abre IIS y haz clic con el botón derecho en Default Web Site (Sitio Web Predeterminado) para añadir nuestro servicio web.

Hosting in IISHosting in IISHosting in IIS

En el cuadro de diálogo Add Application (Añadir Aplicación), asigna el nombre TestAPI a tu servicio y proporciona una ruta al directorio raíz del proyecto de Visual Studio como se muestra abajo.

Adding new application in IISAdding new application in IISAdding new application in IIS

Haz clic en OK y nuestro Servicio API Web está listo.

Para probar si todo funciona bien, vamos a intentar abrir el siguiente URL en cualquier navegador: http://localhost/TestAPI/api/test.

Si nombraste a tu controlador TestController como yo lo hice y si también nombraste TestAPI a tu servicio web en IIS, entonces tu navegador deverá devolver un archivo XML como se muestra abajo, con los valores cadena hello world (hola mundo).

Response from Test ControllerResponse from Test ControllerResponse from Test Controller

Sin embargo, si tu IIS no tiene permisos para la carpeta del proyecto, es posible que veas un mensaje de error que dirá: "The requested page cannot be accessed because the related configuration data for the page is invalid" ("La página solicitada no puede ser accedida debido a que los datos de configuración relacionados con la página son inválidos").

Si recibes este tipo de error entonces puedes resolverlo dándole acceso de lectura/escritura al grupo de usuarios IIS_IUSRS a la carpeta raíz.

Enrutamiento

Ahora veamos cómo está funcionando el URL que le proporcionamos al navegador.

El enrutamiento ASP.NET gestiona el proceso de recibir una solicitud y asignarla a una acción del controlador. El enrutamiento API Web es similar al enrutamiento MVC pero con algunas diferencias; la API Web usa el tipo de solicitud HTTP en vez del nombre de la acción en el URL (como en el caso de MVC) para seleccionar la acción a ser ejecutada en el controlador.

La configuración del enrutamiento para API Web se define en el archivo WebApiConfig.cs. La configuración de enrutamiento predeterminada de API Web ASP.NET es como se muestra a continuación:

La plantilla de enrutamiento predeterminada de API Web es api/{controller}/{id}. Es por esta razón que teníamos "api" en nuestro URL http://localhost/TestAPI/api/test.

Cuando API Web recibe una solicitud GET de un controlador en particular, la lista de acciones coincidentes está conformada por todos los métodos cuyos nombres comienzan con GET. Es lo mismo con todos los otros verbos HTTP. El método de acción correcto a invocar se identifica haciendo coincidir la firma del método.

Esta convención de nomenclatura para métodos de acción puede sobrescribirse utilizando los atributos HttpGet,
HttpPutHttpPost o HttpDelete con los métodos de acción.

Por lo tanto, si reemplazamos nuestro código anterior con esto:

Y abrimos http://localhost/TestAPI/api/test en nuestro navegador, esto aún devolverá el mismo resultado. Si quitamos el atributo HttpGet, nuestra API Web no podrá encontrar una acción que coincida para nuestra solicitud.

Ahora vamos a añadir otro método con el mismo nombre Hello pero con una firma diferente.

Usando este método, ahora podemos controlar lo que está siendo devuelto desde nuestro servicio hasta cierto punto. Si probamos este método llamando a http://localhost/TestAPI/api/test/namaste (nota el parámetro adicional al final del URL), obtendremos la siguiente salida:

Response from Test Controller 2Response from Test Controller 2Response from Test Controller 2

Por lo tanto, ahora tenemos dos métodos llamados Hello. Uno no recibe parámetros y devuelve cademas "hello world", y otro método recibe un parámetro y devuelve "tuparámetro world".

Si bien no hemos proporcionado el nombre del método a ser ejecutado en nuestro URL, el enrutamiento ASP.NET predeterminado comprende a la solicitud como si fuera de tipo GET y, en base a la firma de la solicitud (los parámetros proporcionados), el método particular es ejecutado. Esto está bien si solamente tenemos un método GET o POST en nuestro controlador, pero ya que en cualquier aplicación de negocios real usualmente habría más de un método GET, este enrutamiento predeterminado no es suficiente.

Vamos a añadir otro método GET para ver cómo lo gestiona el enrutamiento predeterminado.

Si ahora generamos nuestro proyecto y llamamos a http://localhost/TestAPI/api/test/ en nuestro navegador, vamos a recibir un error que dice "Multiple actions were found that match the request" ("Se encontraron múltiples acciones que coinciden con la solicitud"), lo que significa que el sistema de enrutamiento está identificando dos acciones que coinciden con la solicitud GET.

Error Response from Test ControllerError Response from Test ControllerError Response from Test Controller

Personalizando el sistema de enrutamiento predeterminado de API Web

Para poder usar múltiples solicitudes GET desde el mismo controlador, necesitamos cambiar el identificador de tipo de solicitud HTTP por un identificador basado en acciones, de manera que puedan invocarse múltiples solicitudes GET.

Esto puede lograrse añadiendo la siguiente configuración de enrutamiento antes de la configuración predeterminada en WebApiConfig.cs.

Ahora prueba los tres métodos ejecutando estos URLs:

La estructura del servicio API Web para dispositivos móviles

Ahora que ya entendimos la idea básica de cómo podemos exponer acciones desde controladores a través de la API, vamos a ver la forma en la que un servicio API puede ser diseñado para los clientes.

Image 9 Web API Service Structure FlowImage 9 Web API Service Structure FlowImage 9 Web API Service Structure Flow

La interconexión de solicitudes API Web ASP.NET recibe solicitudes de la aplicación cliente y un método de acción en un controlador será invocado. A su vez, el método de acción invocará a la capa de negocios para obtener o actualizar información, lo que en turno invocará a la clase Repository para devolver información de la base de datos.

En base a este patrón de diseño, vamos a crear una API de ejemplo que exponga una lista de elementos clasificados como servicio a sus clientes.

Crea una clase llamada ClassifiedModel dentrro de la carpeta Models (Modelos).

Crea dos carpetas BLL y DAL, que representan a la capa de la lógica de negocios y a la capa de acceso a datos.

Crea una clase llamada ClassifiedRepository dentro de la carpeta DAL, en donde vamos a codificar de forma estática algunos datos para la lista clasificada y a exponer la lista a través de un método estático.

Ahora vamos a añadir otra clase ClassifiedService dentro de la carpeta BLL. Esta clase contendrá un método estático para aceder al repositorio y para devolver objetos de negocios al controlador. En base a los parámetros de búsqueda, el método devolverá la lista de elementos clasificados.

Finalmente, ahora crearemos nuestro controlador API Web para los métodos relacionados con el listado clasificado.

De manera similar a la forma en la que creamos nuestro primer TestController, vamos a crear un controlador API con acciones de lectura/escritura vacías llamado ClassifiedsController y a añadir los siguientes dos métodos de acción.

Ahora tenemos dos acciones expuestas a través de la API. El primer método GET será invocado si hay una palabra clave a buscar enviada junto con la solicitud. Si no hay parámetro de entrada, entonces el segundo método GET será invocado. Ambos métodos devolverán una lista de nuestros objetos Classified model.

No olvides añadir todas las referencias necesarias al espacio de nombres de cada uno de los archivos de clases añadidos. Genera el proyecto y ahora estamos listos para probar ambos métodos.

Para mostrar los resultados que contengan el parámetro de búsqueda "house", introduce el siguiente URL en el navegador: http://localhost/TestAPI/api/classifieds/get/house.

Deberemos obtener la siguiente respuesta en el navegador:

GET Request with house as parameterGET Request with house as parameterGET Request with house as parameter

Para ver la lista completa de clasificados, abre el URL sin pasar parámetros: http://localhost/TestAPI/api/classifieds/get/.

Deberás ver el siguiente resultado:

GET Request without any parameterGET Request without any parameterGET Request without any parameter

Podemos añadir cualquier cantidad de acciones y controladores de la misma manera según lo deseen los clientes.

Negociación de contenido

Hasta ahora, hemos visto ejemplos de API que envían respuestas XML a los clientes. Ahora veamos otros tipos de contenido como JSON y la respuesta de tipo imagen, que caen bajo la categoría de negociación de contenido.

La especificación HTTP (RFC 2616) define a la negociación de contenido como "el proceso de seleccionar la mejor representación para una respuesta dada cuando hay múltiples representaciones disponibles". Gracias a la herramienta de negociación de contenido de API Web, los clientes pueden indicar a los servicios API Web el formato de contenido que aceptan, y API Web puede brindar al cliente el mismo formato automáticamente, siempre y cuando el formato esté configurado en API Web.

Solicituando un formato JSON

El encabezado HTTP Accept se usa para especificar los tipos de medios que son aceptables para
el cliente para las respuestas. En el caso de XML, el valor está configurado como "application/xml" y para JSON es "application/json".

Para probar nuestra API con los encabezados HTTP Accept, podemos usar las extensiones disponibles para los navegadores que nos permiten crear solicitudes HTTP personalizadas.

Aquí estoy usando una extensión llamada HTTP Tool disponible para Mozilla Firefox para crear el encabezado Accept que especifica a JSON como el tipo de respuesta.

Creating HTTP Request HeadersCreating HTTP Request HeadersCreating HTTP Request Headers

Como puedes ver en la imagen, la respuesta que está siendo recibida se encuentra en formato JSON.

Un archivo de imagen como respuesta

Finalmente, veamos cómo podemos enviar un archivo de imagen como respuesta a través de API Web.

Vamos a crear una carpeta llamada Images y a agregar una imagen llamada "default.jpg" dentro de ella. Luego vamos a añadir el siguiente método de acción dentro de ClassifiedsController.

Además deben incluirse estos dos espacios de nombres: System.Web, System.Web.Http.

Aquí estamos creando una respuesta HTTP usando la clase HttpResponseMessage y estableciendo los bytes de la imagen como contenido de la respuesta. Además, estamos configurando el encabezado Content-Type con el valor "image/png".

Ahora, si invocamos a esta acción en nuestro navegador, la API Web enviará nuestra imagen default.jpg como respuesta: http://localhost/TestAPI/api/classifieds/Getimage/.

Sending Image as response from Web APISending Image as response from Web APISending Image as response from Web API

Conclusión

En este tutorial vimos cómo es que una API Web ASP.NET puede crease y exponerse fácilmente a los clientes como métodos de acción de controladores MVC. Vimos el sistema de enrutamiento predeterminado y el personalizado, creamos la estructura básica de un servicio API de aplicación de negocios en tiempo real, además de ver diferentes tipos de respuestas.

Y si estás buscando herramientas adicionales para comprar, revisar o usar, revisa la oferta de .NET en CodeCanyon.

Espero que hayas disfrutado de este tutorial y que lo hayas encontrado útil para construir tus APIs Web para dispositivos móviles. ¡Gracias!.

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.