Creando una API Web (RESTful) con ASP.NET Core 3.1

Explorando verbos HTTP y realizando operaciones CRUD

En este tutorial utilizaremos Visual Studio 2019 y ASP.NET Core 3.1 para crear una Web API (RESTful).

¿Qué es un API?

Una interfaz de programación de aplicaciones (API) es una interfaz o un protocolo de comunicaciones entre diferentes partes de un programa de computadora que tiene la intención de simplificar la implementación y mantenimiento del software. Una API puede ser un sistema basado en la web, un sistema operativo, un sistema de base de datos, hardware o una librería.

Una API Web

Cuando es utilizada en el contexto de desarrollo web, una API es típicamente definida como un conjunto de especificaciones, tales como mensajes de solicitud HTTP, junto con una definición de la estructura de los mensajes de respuesta, usualmente en formato XML o JSON.


Es la definición más o menos formal, ahora trataremos de entenderlo de la forma más práctica.


Con una API Web nos debemos entender con verbos HTTP. En particular,

• GET- para leer datos
  


• POST- para crear nuevos datos
  


• PUT- para modificar datos
  


• DELETE- para eliminar datos
  

Hay otros verbos, pero básicamente son los verbos a utilizar en las mayorías de APIs.


Estos verbos HTTP forman el fundamento de las operaciones CRUD: Create, Read, Update, Delete, que son operaciones comunes para utilizar con una base de datos, cuando los hayamos implementado, es que hemos creado una API RESTFul.


Cuando se crea una API Web, estamos construyendo un componente back-end. El front-end puede ser algo que podemos crear también, pero usualmente otra aplicación es la que consumirá nuestra API Web.

Herramientas

Para este tutorial necesitamos Microsoft Visual Studio, en mi caso la versión Community.


Se necesita un software para probar la API Web, para lo cual existen herramientas gratuitas como Advanced REST Client.

Estructura del tutorial

Este tutorial tiene dos secciones:

• SECCIÓN 1 — al inicio usaremos Visual Studio y experimentaremos con el controlador por defecto que Visual Studio genera automáticamente.
  


• SECCIÓN 2 — crearemos nuestro propio controlador para manejar las operaciones CRUD.
  

SECCIÓN 1

Iniciamos Visual Studio y creamos un nuevo proyecto.





Ahora elegiremos el tipo de proyecto. El tipo de proyecto que se necesita es Aplicación Web ASP.NET Core. En la descripción se indica que con ese proyecto se pueden "crear aplicaciones Web de ASP.NET Core y API web".





Haga clic en Siguiente e ingrese un nombre para el proyecto y ubicación del proyecto. Yo lo bauticé como CRUDWebAPI. El siguiente paso es hacer clic en el botón Crear.

Finalmente seleccionamos una de las opciones, API como vemos en la imagen o aplicación Web (MVC). Con ambos proyectos podemos crear servicios HTTP RESTful. Seleccionar API nos permitirá tener un controlador de inicio (WeatherForecastController) con algunos métodos HTTP para comenzar. Pero si seleccionamos la opción MVC, tendremos algunos componentes "View" (vistas) para trabajar un front-end. Como el tutorial trata de crear un API, seleccionaremos la opción API. Luego "Crear".





En el Explorador de soluciones, podemos ver los archivos de la solución.





Lo siguiente que vamos a hacer, es examinar el controlador de ejemplo creado, WeatherForecastController.cs, donde haremos la mayor parte del trabajo.


En el Explorador de soluciones, abramos el archivo WeatherForecastController.cs. Este archivo tendrá algunos métodos creados automáticamente por Visual Studio que podemos elegir utilizar o no.

Podemos hacer modificaciones a estos archivos o se pueden utilizar tal cual. Al ejecutar el proyecto, Visual Studio nos indica que puede instalar un certificado HTTPS de prueba. También habrá que modificar el archivo launchSettings.json para que no se abra el navegador cuando se ejecute el proyecto, después de todo, es un API y no una página web.





Hay que cambiar el atributo "launchBrowser" a "false".

Prueba

Ejecuta la solución.

No deberías ver nada, ya que está configurada la solución para no iniciar un navegador.


Iniciamos el Advanced REST client (enlace) para las pruebas.


En el campo "Method", seleccionar "GET", en "Request URL" ingresar la dirección https://localhost:{port}/weatherforecast, luego hacer clic en el botón "SEND". Se recibirá el resultado del método GET.





Para familiarizarnos, hagamos unos cambios en la aplicación.


Detener el servidor, eligiendo "Detener depuración".


Modifiquemos el controlador WeatherForecastController, según lo siguiente.


Ejecuta la solución para ver que se obtiene pasando ahora una fecha.





Ahora tenemos una API web funcionando.

SECCIÓN 2

Creando tus propias rutas y métodos — Vayamos un poco más lejos

No hay nada malo con el controlador por defecto WeatherForecastController que Visual Studio crea. Nos da un ejemplo de como es una API Web. Pero la idea es aprender por eso:

• Crearemos nuestro propio controlador.
  


• Definiremos rutas a nuestros propios métodos para realizar acciones GET/POST/PUT/DELETE.
  

Haciendo esto, nos dará mayor control sobre lo que nuestra API Web es capaz de hacer. A pesar que no nos conectaremos a una base de datos, realizaremos operaciones CRUD utilizando un ArrayList y agregar, leer, modificar y eliminar usuarios desde el ArrayList.


Implementaremos dos operaciones GET. Uno en que obtengamos todos los usuarios y uno para obtener un usuario en específico.

Agregando nuestro propio controlador

En el Explorador de Soluciones, haz clic en la carpeta Controllers y elige Agregar/Controlador.





Elija Controlador de API con acciones de lectura y escritura.





Llámalo UserController. Esto crea el controlador UserController.cs.





Antes de modificar UserController, hagamos un cambio al archivo launchSettings.json, localizado en la sección Properties en el Explorador de soluciones. Aquí quitaremos o comentaremos la propiedad launchUrl. No es necesaria en el tutorial.

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:5000",  // Use port 5000
      "sslPort": 0  //44363 - remove https for testing
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": false,     // Keep browser from running
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebAPI": {
      "commandName": "Project",
      "launchBrowser": false, // Keep browser from running
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}
			

Ahora modifiquemos UserController.cs. Utilizaremos un ArrayList para almacenar nombres de usuario. Esta será la base de datos ficticia para operaciones CRUD.


Necesitamos agregar una sentencia "using" al inicio para darnos acceso a la colección ArrayList.

Agregando nuestros propios métodos

Agregaremos los siguientes métodos a UserController.cs.

• GetAllUsers — para obtener una lista de todos los usuarios. Es un método GET.
  


• GetUser — para obtener un usuario especifico basado en un id. Será un método GET.
  


• SaveNewUser — para agregar un usuario a nuestra colección (ArrayList, nuestra base de datos ficticia.) Este es un método POST.
  


• UpdateUser — para actualizar un usuario. Será un método PUT.
  


• DeleteUser — para quitar un usuario de nuestro ArrayList. Será un método DELETE.
  

Nota: para propósito de prueba, regresaremos el mismo ArrayList después de cada operación. Cada método devolverá un ArrayList. Esto no siempre es así. Casi nunca es así. El retorno de un método de un API debe ser un indicador de éxito o fallo.





Adicionalmente al crear cada método para manejar la operación, también deberemos especificar la ruta en el manejador del método.

Sintaxis e Información de uso

Tendremos una ruta maestra. De modo que quien consuma el API tendrá que hacer una solicitud a http://localhost:{puerto}/api/User.


Pero también habrá otras rutas para los métodos. El consumidor puede estar utilizando http://localhost:{puerto}/api/User/GetAllUsers. Cuando el consumidor ingrese a esa ruta, nuestra API Web seguirá la ruta e invocará el método GetAllUsers.


Reemplaza el contenido de UserController.cs con lo siguiente. Nota lo que está seleccionado.

Probando

Ejecuta tu solución. Abre Advanced REST Client o cualquier otra herramienta para probar APIs web. Agregaremos usuarios, y probaremos cada método.


Registrar un nuevo usuario




Obtener el listado de todos los usuarios




Obtener la información de un usuario especifico




Modificar la información de un nuevo usuario




Eliminar un nuevo usuario




Eso es todo, al menos para este tutorial.

Conclusión

Realmente hay mucho más para aprender, pero digamos que esto es un buen inicio para que podamos crear nuestras API web RESTful utilizando ASP.Net Core 3.1, para cualquier tipo de Web API, ya que básicamente utilizan los mismos verbos HTTP: GET, POST, PUT, DELETE.