Reglas RestFull

A la hora de desarrollar, cada uno de nosotros es diferente y tiene sus propias "maneras" de organizar y entender su trabajo, sin embargo cuántas veces no te ha tocado la difícil tarea consumir una API y las enpoints son muy largas y no dan referencia clara de que nos devuelve como respuesta. Para evitar ese tipo de contratiempos y proporcionar un acceso efectivo a nuestra API, te comparto las reglas preestablecidas y avaladas por los pesos pesados del desarrollo, que deberías tomar como buena práctica desde ya, al definir los enpoints de tu aplicación.

1.- Usa sustantivos no verbos

Cuando definimos nuestros enpoints, siempre cometemos errores a la hora de especificar o declarar nombres. Para la declaración de un enpoint es importante utilizar sustantivos. Con el objetivo de tener una fácil compresión a la hora de interpretar la documentación.

/* Aqui podemos pensar, que este enpoint nos va a obtener los carros o clientes*/
/getCars 
/getClients

Como podemos observar, al declarar la ruta del enpoint, estamos colocando un verbo, claro que al tratar de traducirlo o interpretarlo mediante la URL, nos indica que nos va a traer todos los vehículos o clientes dependiendo de la ruta. Esta es la forma incorrecta de declararlo y en muchos casos son errores comunes que cometemos todos (Me incluyo) cuando empezamos a desarrollar.

/* Method GET */
/cars
/clients

2.- Sustantivos en plural

Otro de los problemas comunes es que en las rutas empezamos a combinar singular y plural, a pesar de que hayamos creado los enpoints con sustantivos.

/car/1
/cars

Generalmente definimos un singular para hacer referencia a lo que debemos obtener un carro con su id correspondiente y el plural para obtener todos los vehículos. Pero en esta ocasión todas las rutas a declarar serán en plural los sustantivos

/cars/1
/cars

3.- Define correctamente el tipo de petición a realizar

Es importante dejar muy claro qué tipo de método corresponde a cada enpoint, los 4 más comunes son GET, POST, PUT y DELETE.

GET: Es el método que nos define que se puede obtener datos y el comúnmente usado al obtener datos de una base de datos (SELECT).

POST: Por otro lado este método define la inserción de datos, el ejemplo más claro es cuando la función hace uso de INSERT en la base de datos.

PUT: Erróneamente asimilado con POST, este método define la actualización de datos. (UPDATE en la base de datos).

DELETE: Tal cual su nombre lo indica, define la eliminación de registros (DELETE en la BD)

4.- Códigos de estado

Uno de los errores típicos y comunes al construir una API, suele ser el envío de códigos de estado en la petición. Ejemplo:

Durante una petición se devuelve un código 200, cuando se ejecuta de forma correcta. Sin embargo en este caso el código se devuelve en el cuerpo de la respuesta.

Petición
========
PUT /facturas/123

Respuesta
=========
Status Code 200
Content:
{
  success: false,
  code:    734,
  error:   "datos insuficientes"
}

Este es un error común que tiene varios inconvenientes, los dos principales son:

1. No es REST ni es estándar.
2. El cliente que haga uso de esta API debe conocer la forma particular en la que se devuelven las respuestas y cómo trabajar con los errores de la misma

Debemos estandarizar los errores y códigos de error en nuestra API, ya que el cliente espera respuestas rápidas y eficientes, ocupando la menor cantidad de líneas de código.

5.- Usa versiones

Que nuestra API cuente con un número de versión y mantenerlo a la vista de las peticiones, es una muy buena práctica, ya que nos permite tener control al corregir errores o al hacer actualizaciones en la misma.

https://localhost:8181/v2/clients

Como conclusión, siguiendo estas simples reglas, tendremos nuestras APIS bien definidas y totalmente claras a la hora de liberarlas a nuestro equipo.