Lo que necesitas saber para construir tu primer RESTful API

Usualmente este tipo de APIs sirven para exponer los datos de un sistema o aplicación, por lo tanto un CRUD puede ser expuesto por medio de REST en donde hay que olvidarse del estándar SOAP. Para crear una RESTful API primero necesitas conocer las bases de una Arquitectura Orientada a Recursos y entender cómo debes exponer, actualizar y crear los recursos de tu aplicación. Para iniciar con REST deberás considerar los siguientes puntos.

Manipulación de los recursos en REST

A diferencia de SOAP en donde hay diferentes alternativas de protocolos a utilizar, en REST no invertimos esfuerzos en tomar esta decisión ya que HTTP(S) es el protocolo utilizado. Para obtener un simple dato no necesitamos enviar un XML al servidor (como SOAP). Es suficiente realizar una petición GET a una URL por medio de HTTP, en donde la mayoría de veces no enviamos datos en este tipo de acciones, salvo algunos casos en donde es requerido por cuestiones de seguridad por mencionar alguno. En REST se puede utilizar XML o JSON para intercambiar datos aunque JSON es el más utilizado.

Por ejemplo para obtener la lista de productos basta con realizar un HTTP GET al recurso productos:

GET /api/productos -> https://host/api/productos

REST utiliza métodos HTTP

En REST se utilizan los métodos GET, PUT, POST, DELETE entre otros para indicar el tipo de operación que se desea realizar sobre el recurso.

GET: Se utiliza para obtener una representación de un recurso.

GET /api/productos - obtiene una lista de productos 
GET /api/productos/{idProducto} - obtiene los datos de un producto específico

POST: Se utiliza para crear una entidad a un recurso específico. En esta acción se debe adjuntar el JSON con los datos dentro del “Body” de la petición HTTP.

POST /api/productos - crea un producto nuevo
{
 "idProducto": "23",
 "nombre": "iPhone 11 Pro 256 GB",
 "descripcion": "Teléfono inteligente de Apple ",
 "precio": 1000.00,
 "rating": 4
}

PUT: Se utiliza para actualizar una entidad de un recurso específico. En esta acción se debe adjuntar el JSON con los datos dentro del “Body” de la petición HTTP.

PUT /api/productos/23 - actualiza los datos de un producto específico
{
 "nombre": "iPhone 11 Pro 256 GB",
 "descripcion": "Teléfono inteligente de Apple ",
 "precio": 850.00,
 "rating": 4
}

DELETE: Se utiliza para eliminar una entidad de un recurso específico. En esta acción se debe adjuntar en la url valor que identifica a la entidad dentro del recurso.

DELETE /api/productos/23 - elimina el producto específico basado en el id adjunto en la URL

Si te fijas bien, en REST las URLs no contienen verbos o acciones ya que el verbo HTTP nos indica la acción del recurso y el recurso está especificado dentro de la URL.

Tomando en cuenta lo anterior algo que NO deberías hacer es exponer tus recursos como:

POST /api/ObtenerProductos
POST /api/ActualizarProductos
POST /api/CrearProductos

Se recomienda que dentro de la URL no especifiques acciones o verbos como “CrearProductos”, “ObtenerUsuario” ya que por ser una arquitectura orientada a recursos estos recursos deben de ser accesibles y manipulables por medio de la URL y el verbo HTTP.

Los códigos de estado de respuestas HTTP

Un servicio REST debe de responder con códigos HTTP dependiendo de lo que quiera comunicarle al cliente. Esto permite que el cliente que consume el REST API pueda manejar diferentes escenarios de una mejor manera y que esto no impacte negativamente en la experiencia del usuario. Los más utilizados son:

• 200-299: Indican buenas noticias, ya que la petición fue aceptada.
  • 200 OK: Indica que la operación fue realizada correctamente.
  • 201 Created: Indica que la operación se realizó correctamente, se utiliza para indicar que se creó un recurso en un POST.
• 300-399: Indican redireccionamiento de una página a otra.
  • 301 Moved Permanently: Indica redireccionamiento permanente.
  • 302 Found: Indica redireccionamiento temporal, se diferencia del 301 en que toda las caracteristicas del SEO no se transportan a la nueva URL.
• 400-499: Indican que el cliente que hizo la petición no está en la capacidad de resolverla.
  • 400 Bad Request: Indica que los datos dentro de la petición no eran los correctos, se utiliza en POST y PUT cuando no se cumple una validación o formato.
  • 404 Not Found: Indica que el recurso solicitado no fue encontrado.
  • 401 Unauthorized: Indica que el cliente no está autorizado a acceder al recurso por lo que es necesario identificarse antes de realizar la operación.
  • 403 Forbidden: Indica que el cliente no tiene permisos, en este caso el cliente ya se identificó pero no tiene el permiso para acceder al recurso.
• 500-599: Indican el registro de errores en el servidor al que se hizo la petición.
  • 500 Internal Server Error: Indica que algo falló y no está relacionado con ninguno de los errores mencionados anteriormente, por lo general esta respuesta es cuando algo falla de manera imprevista.
  • 501 Not Implemented: Indica que la peticion hecha por medio del verbo no ha sido implementada o simplemente el servidor no tiene la capacidad para resolverla.
  • 502 Bad Gateway: Indica que el servidor esta actuando como puerta de enlace o proxy y recibió una respuesta no válida del servidor original.
  • 503 Service Unavailable: Indica que el servidor que está actuando como puerta de enlace o proxy recibió una respuesta no válida del servidor original, comunmente porque no esta disponible o esta caído.

Lenguajes y frameworks para construir una REST API

Para desarrollar tu primer REST API necesitas un lenguaje utilizado en backend, además puedes considerar un framework para facilitarte el proceso. Entre los más populares están:

Lenguaje	Frameworks
C#	ASP.NET Core/5/6/7
Java	Spring Boot, Quarkus, TomEE
JavaScript	Express, NestJS
Python	Flask, Django

Claro que existen más lenguajes y frameworks que podrías considerar, la elección de qué tecnología utilizar dependerá de factores como: experiencia previa en el lenguaje, lenguajes conocidos por tu equipo de trabajo, documentación disponible, ecosistema y restricciones de tu entorno, herramientas para el desarrollo, etc.

Al final la decisión será tuya o de tu equipo, elije la tecnología que cumpla con diferentes criterios previamente definidos. También puedes considerar solo el hecho de que quieres aprender algo nuevo, entonces debes buscar recursos para aprender como: documentación, libros, tutoriales y cursos en línea.

Con esta información en cuenta ya estás listo para empezar a construir tu primer REST API.