Guía para Escribir API Rest Profesionales

• Métodos HTTP
• Códigos de Estado HTTP
• Ejemplos de Uso de Métodos HTTP
• GET
• POST
• PUT
• DELETE
• PATCH
• Buenas Prácticas

A lo largo de mi carrera como desarrollador, he tenido la oportunidad de integrar numerosas API Rest de terceros. Sin embargo, en muchas ocasiones me he encontrado con que dichas APIs no cumplen con las buenas prácticas o no son lo suficientemente claras. Esta falta de estandarización y claridad puede llevar a malentendidos, errores y un aumento en el tiempo de desarrollo.

Es por esto que he decidido escribir este pequeño tutorial. Mi objetivo es compartir mi experiencia y conocimiento para que más desarrolladores puedan crear sus APIs de forma entendible para otros. En esta guía, abordaremos los conceptos básicos necesarios para diseñar y construir APIs que no solo funcionen correctamente, sino que también sean fáciles de comprender y de integrar.

Las APIs (Interfaz de Programación de Aplicaciones) son esenciales en el desarrollo de servicios web modernos. En este artículo, aprenderemos a escribir APIs REST profesionales, respetando los métodos HTTP y utilizando códigos de estado apropiados.

Métodos HTTP

Los métodos HTTP permiten definir la operación que se desea realizar en el recurso especificado. A continuación, se describen los métodos más comunes:

• GET: Utilizado para obtener datos de un servidor.
• POST: Utilizado para enviar datos a un servidor y crear un nuevo recurso.
• PUT: Utilizado para actualizar un recurso existente.
• DELETE: Utilizado para eliminar un recurso existente.
• PATCH: Utilizado para realizar una actualización parcial en un recurso.

Códigos de Estado HTTP

Los códigos de estado HTTP indican el resultado de la solicitud realizada al servidor. A continuación, se describen algunos de los códigos más comunes:

Muchas veces me encuentro con respuestas GET con código 200 OK y que dentro de la respuesta llega el error Not Found, desde mi punto de vista esto es un error de diseño y no permite integrar y controlar las respuestas al consumir el API.

Ejemplos de Uso de Métodos HTTP

Veamos como usar los diferentes metodos HTTP, partiendo de la explicación inicial. 

GET

El método GET se utiliza para obtener información de un recurso. Por ejemplo, si queremos obtener información de un usuario con id 1:

GET /users/1 HTTP/1.1
Host: example.com

Respuesta:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "John Doe"
}

en llegado caso que el usuario con ID 1 no exista la forma correcta de responder seria algo similar a esto:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "El usuario no existe" 
}

POST

El método POST se utiliza para crear un nuevo recurso. Por ejemplo, para crear un nuevo usuario:

POST /users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "Jane Doe"
}

Respuesta:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 2,
  "name": "Jane Doe"
}

PUT

El método PUT se utiliza para actualizar un recurso existente. Por ejemplo, para actualizar el nombre del usuario con id 1:

PUT /users/1 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "John Smith"
}

Respuesta:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "John Smith"
}

DELETE

El método DELETE se utiliza para eliminar un recurso existente. Por ejemplo, para eliminar el usuario con id 1:

DELETE /users/1 HTTP/1.1
Host: example.com

Respuesta:

HTTP/1.1 200 OK

PATCH

El método PATCH se utiliza para realizar una actualización parcial en un recurso. Por ejemplo, para actualizar parcialmente el nombre del usuario con id 1:

PATCH /users/1 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "Johnny"
}

Respuesta:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "Johnny"
}

Buenas Prácticas

• Usar rutas claras y coherentes.
• Implementar autenticación y autorización.
• Documentar la API con herramientas como Swagger.
• Manejar errores de manera eficaz.

Siguiendo estas buenas prácticas y utilizando adecuadamente los métodos HTTP y códigos de estado, podrás crear APIs REST profesionales y robustas.

Entiendo que para muchos puede parecer que estas "bunas practicas" ya sean obsoletas, pero para mi siguen vigentes y mantienen un orden claro en las integraciones con APIs.