Este post fue publicado originalmente en mi sitio personal

Para ayudar a dominar los códigos de estado al crear API's; dejo este resumen de los códigos HTTP mas usados o mas comunes:

1. 1XX -> Información

2. 2XX -> Petición correcta

3. 3XX -> Redirection

4. 4XX -> Error de cliente

5. 5XX -> Error de servidor.

Hay un tweet de @stevelosh, que define de manera graciosa el objetivo de cada rango o familia de codigos HTTP*.*

English

Spanish

Algunos de los códigos HTTP más usados

Rango 100

• 100 : Es un código muy raro en http, y se puede encontrar al usar websocket. Los websockets usan el código 100 para intercambiar cierta información de protocolo que sirve para establecer la conexión.

Rango 200

• 200 : OK

• 201 : CREATED, devuelve una cabecera location, que es una URL de donde se puede consultar el nuevo recurso, creado.

• 202 : ACCEPTED, encolado en caso de usar colas servicios o workers, también devuelve una cabecera location que es una URL de donde se puede consultar el recurso.

• 204 : NO CONTENT, es como si el servidor te dijera, "te entendí pero no voy a decir nada".

Rango 300

• 301 : MOVED PERMANENTLY, es usado para redirección a largo plazo, el navegador guarda en cache la redirección. Ejm: Cuando la pagina cambio de nombre.

• 302 : ENCONTRADO Y REDIRECCIÓN TEMPORAL, redirecciona a otro lugar. Ejm: Redirección en proceso de login.

• 303 : SEE OTHER

• 304 : NOT MODIFIED, se usa cuando el servidor web implementa algún tipo de cache.

• 307 : TEMPORARY REDIRECT

• 308 : PERMANENT REDIRECT

Importante, tener en cuenta 👇

Los códigos 307 y 308 funcionan como los códigos de respuesta 302 y 301 respectivamente (Redireccion temporal y permanente).

Pero debemos recordar que en una request que use los métodos POST| PUT| DELETE y retorne los códigos 301 o 302; los métodos (POST|PUT|DELETE) se convertiran en una peticion con método GET

• 301 y 302, cambia el método de la peticion por GET.

• 307 y 308, mantienen el método de la peticion(POST, PUT, DELETE).

Rango 400

Se usan cuando el error ha sido provocado por algo que realizo el cliente,

• Ejemplo:

  • Se envió una petición/request mal.

  • No se envió un parámetro obligatorio o requerido.

  • Hace una peticion/request a un URL que no existe.

• 400 : BAD REQUEST.

• 401 y 403 : UNAUTHORIZED AND FORBIDDEN ERRORS.

• 404 : NOT FOUND.

• 410 : GONE, `ya no existe` o `se ha ido`, **Nuevo**

  • Ejm: Cuando se publica un tweet polémico y decides borrarlo; y cuando alguien con el URL quiere volver a ver el tweet, podría devolver 410, porque ha sido eliminado y ya no existe.

• 422 : UNPROCESSABLE ENTITY, en caso de que los parámetros pasados sean inválidos.

  • Ejm: no se envía parámetro correcto o que es obligatorio en la petición.

• 451 : UNAVAILABLE FOR LEGAL REASONS.

Rango 500

En este rango, existen muchos códigos de estados, pero el mas importante es el 500. Se usa cuando hubo un error interno en el servidor.

• Ejm:

  • Una excepción en el código fuente.

  • Un error en la base de datos.

  • Una conexión dañada a algun servidor o peticion, puede darse el caso que nuestro servidor este consultando por detrás a otro servicio y este no este respondiendo a tiempo o con timetout, etc.

• 500 : INTERNAL SERVER ERROR.

• 502 : BAD GATEWAY.

• 503 : SERVICE UNAVAILABLE.

• 504 : GATEWAY TIMEOUT, el servidor esta tardando mucho en responder.

Conclusiones y Recomendaciones

Debemos tener en cuenta que como desarrolladores, a pesar de conocer el error y el códito de estado HTTP exacto que podríamos usar para retornar en el response, aun siendo buena práctica lo anterior, debemos tomar en cuenta desde el punto de vista de la Seguridad, que código debemos usar.

Sería mejor responder un código más genérico y no ser tan específico con el código de estado HTTP que retornemos. Ejm: 500 o 404.

El motivo de esto es para proteger la seguridad de nuestra aplicación o servidor de posible hackers o personas mal intencionadas, y evitar que indaguen en los códigos de respuesta HTTP ya que si detallamos especificando el código HTTP les facilitamos encontrar debilidades que pueda tener nuestro sistema y que no hayamos detectado aún.

Recursos

Aqui hay algunos recursos donde podemos ver mas a detalle los códigos de estado HTTP:

• HTTP Statuses

• HTTP Cats

• HTTP Dogs

• HTTP Status Codes

Referencias

• Obtenido de investigaciones en internet.

• Libro Express in Action.

• Tweet de @stevelosh

• Explicación en el canal de makigas.es.

Según wikipedia el significado de idempotencia es la propiedad de realizar una acción determinada varias veces, y aún así, conseguir el mismo resultado que se obtendría si se realizara una sola vez.

En el caso de HTTP, específicamente en los verbos HTTP, la idempotencia nos dice que:

La ejecución repetida de una petición, con los mismos parámetros, sobre un mismo recurso; tendrá el mismo efecto en el estado de nuestro recurso, si se ejecuta 1 o N veces. Es decir siempre tendremos el mismo resultado sin importar el numéro de ejecuciones.

Verbos HTTP Idempotentes Vs No Idempotentes

Debemos tener en cuenta, que tambien existen verbos HTTP idempotentes y no idempotentes.

En la siguiente tabla vemos los verbos que son y no son idempotentes:

Verbos no idempotentes

Debemos tener en cuenta, que existen verbos HTTP no idempotentes. Pero es buena práctica, respetar el principio de idempotencia para evitar efectos secundarios o no deseados al ejecutar nuestros recursos http.

La ejecución repetida, usando un verbo no idempotente, con los mismos datos sobre un recurso no tendrá el mismo efecto.

Ejemplo verbo No idempotente

Tenemos un API la cual, tiene un endpoint que tiene como recurso una entidad USUARIO parte de una base de datos de un blog.

Si hacemos uso de una petición POST http para crear un artículo, como POST es un verbo no idempotente.

Si ejecutamos la siguiente petición POST /api/v1/usuario la primera vez, con los siguientes datos, obtendremos como resultado la creacion del recuso usuario Jhon Doe.

POST /api/v1/usuario
{
    "nombre" : "Jhon Doe",
    "email": "jdoe@doe.com"
}

¿Que pasa si ejecutamos una segunda vez esta petición POST /api/v1/usuario con la misma información en el cuerpo de la petición? -- dependiendo de la lógica dentro de nuestra API podemos tener los siguientes resultados :

1. Si no estamos validando que el email se repita, el resultado en cada ejecución, será crear cada vez un nuevo recurso _usuario_ en la base de datos.

2. Si validamos el email obtendremos un error porque ya existe un usuario con el mismo email en la base de datos.

Ejemplo verbo Idempotente

En este caso vamos a usar el verbo http PUT; realizaremos una peticion de creación/actualización sobre un recurso USUARIO especifico de la base de datos con datos usados en el cuerpo del ejemplo anterior.

Si ejecutamos la siguiente petición PUT /api/v1/usuario/1 creara un nuevo USUARIO en caso de no existir, o lo modificara en caso de haya cambiado algo en el existente.

PUT /api/v1/usuario/1
{
  "nombre" : "Jhon Doe",
  "email": "jdoe@doe.com"
}

Si ejecutamos esta petición por primera vez, creara el nuevo recurso usuario/1 en caso de no existir.

Pero si repetimos y ejecutamos la misma petición N veces, con el verbo idempotente PUT, incluso enviando los mismo parámetros al mismo recurso /1, este se actualizara y se mantendrá igual, es decir tendremos el mismo estado o resultado.

Pero que pasa si ejecutamos la petición cambiando algo de información, por ejemplo el recurso /2, el efecto que tendrá sera crear un nuevo recurso.

PUT /api/v1/usuario/2
{
  "nombre" : "Jhon Doe ",
  "email": "jdoe@doe.com"
}

Conclusiones

Es importante tener en cuenta que este comportamiento de idempotencia no solo se produce simplemente por usar uno de los verbos idempotentes, sino que es necesario implementar y respetar este principio al momento de diseñar la lógica de nuestra API.

Este post fue publicado originalmente en mi sitio personal

Para mejorar cada vez tu productividad cuando usas git desde la terminal, considero hay 2 cosas importantes que te pueden ayudar a conseguirlo:

1. Trabaja en buenos alias (git y linux) y mejoralos contantemente.

2. Usar herramientas como commitizen para asegurar una convención al momento de escribir commits.

Te ha pasado, que estás en la zona/concentrado, terminas de corregir un error, o de crear una nueva funcionalidad, y te llega ese pequeño momento de frustración en el que no sabes exactamente qué escribir en tu mensaje de commit? (🤦‍♂️ o tal vez solo soy yo!!)

Es molesto sobre todo, cuando te equivocas y tienes que hacer un --amend al darte cuenta de que no lo describiste bien y tener que repensarlo, buscar el último comando, escribir nuevamente el mensaje, etc., aún más si ya hiciste push!!.

Si esto te ha pasado, creo que esto te va a interesar.

1. ¿Por qué tanta conmoción por un mensaje de commit?

No solo es un mensaje de commit, es la historia y evolución de nuestro desarrollo. Sí, Git es una herramienta esencial en nuestro flujo de trabajo como programadores. Pero igual de importante, es escribir correctamente nuestros mensajes de commit, mejor cuando seguimos una convención como conventional commits.

Lo que queremos lograr con esto, es mantener un historial limpio y fácil de leer de los cambios(logs) de nuestro código, y convertirlo en una narrativa que solo al leerla, podamos descubrir y entender el proceso y evolución de nuestro software.

The git log is a narrative of how development is progressing. Keep it clean.
Juan J. Merelo

2. ¿Por qué commitizen y no simplemente un cliente gráfico de Git?

Es cierto y válido, actualmente existen herramientas gráficas que facilitan el trabajo, al versionar tu código con git, y sobre todo al visualizar el historial de cambios que has realizado; pero aún no conozco alguno, que integre linters de commits como conventional commits. (Si conoces alguno que sea open source por favor házmelo saber!!)

Aparte de esto, la ventaja que obtendremos al usar commitizen y alias a través del terminal, en mi opinión, no tiene nada que envidiarle a una app gráfica, ! Bueno la UI de logs tal vez!; pero como dicen por ahí, “para gustos, colores!". Además, encontré una forma de arreglar esto con un alias, el que veremos más adelante.

Basta decir que por el gusto de usar la terminal, además de que, está buenísimo entender bien las bases de git y saber que comandos estás usando realmente; así no tener dificultades con alguna herramienta que te puedas encontrar en el futuro.

3. Requisitos

Por lo general, me gusta trabajar sobre linux, por eso para seguir este post y empezar tu configuración es necesario lo siguiente:

• Tener una máquina con linux o WSL instalado, si estás en windows 10.

• Tener instalado Git

• Tener instalado npm y Node.js

Ten en cuenta que sería bueno que ya conozcas las bases de git para entender o darle sentido a esta lectura, pero aun así, intentaré hacerlo fácil de seguir.

4. Mi configuración de espacio de trabajo para Git

Como ya te debes imaginar, mi configuración al rededor de Git son alias de linux, git aliases y commitizen.

• Linux Alias → se usan para encapsular la ejecución de un conjunto de comandos, en un solo comando abreviado en la terminal, dicho de otra formas, son abreviaciones de nuestros comandos que se configuran en tu sistema linux, en este caso 'git', Ejm:

    # Comando largo
    git commit -m 'mensaje commit'
  
    #Comando abreviado
    gc 'mensaje commit'
  

• Git aliases → esta es una característica de Git parecida a la de linux alias, ayuda a simplificar en abreviaciones mas cortas la ejecución de los comandos de git.Ejm:

    $ git config --global alias.co checkout
    $ git config --global alias.br branch
    $ git config --global alias.ci commit
    $ git config --global alias.st status
  

• Commitizen → Commitizen nos permite escribir mensajes de commits de forma guiada y rapida a travez de CLI o yo podria decirle TUI.

  Commitizen es un cli "command line interface tool" que nos ayuda a escribir mesajes de commits mas amigables siguiendo un estandar de convenciones y buenas practicas, con la ayuda de linters y herramientas que puedes configurar.

Puedes encontrar mi configuración de linux alias y git aliases aquí:

5. Linux 'alias' para acortar comandos

Por lo general al usar la terminal, escribes un comando o combinación de comandos, por ejemplo git o ls. Aveces es un poco molesto cuando tienes que repetir muchas veces el mismo comando (y eso que este es uno de los cortos), entonces es aquí donde puedes usar un alias.

En este caso configuro un alias g para el comando git .

• En sistemas unix donde solemos usar zsh o bash, etc; configuramos un alias de esta forma → alias g=''.

Ahora abrimos nuestro archivo de configuracion del shell que uses ya ~/.bashrc de bash o ~/.zshrc de zshell (es el que uso) y agregamos esta linea alias g=git al final del archivo o en la sección #alias si esta ya existe .

Ahora si nos dirigimos a nuestra terminal, en el directorio de uno de nuestros repositorios de git, podemos usar git, reemplazando el comando git por g, Ejm:

En la imagen anterior vemos que no tenemos diferencia en el resultado al escribir el comando git status o g status debido a que a la configuración del alias harán lo mismo "mostrar el estado del repositorio".

Bien logramos acortar el comando git, pero como acortamos las opciones o argumentos que van el comando git?

Esto lo podemos hacer creando un alias con el comando y los argumentos que necesitemos, un ejemplo alias gst=git status, asi al escribir gst en nuestra terminal obtendremos la salida del comando git status. Pruebalo!!

En el caso de que uses Zsh, existen alias ya pre-configurados para tu comodidad. Esto lo consigues instalado un framework para zsh llamado Oh-My-Zsh, y activando su plugin de Git Ohmyzsh existente en el framework.

En la siguiente imagen puedes ver los alias pre-configurados en el plugin git de oh-my-zsh.

Aunque estos alias son muy útiles, siempre toma un tiempo aprenderlos, incluso no llegas a usarlos todos. Por eso te recomiendo que estos alias los tengas de referencia para crear los tuyos y asi irles aprendiendo durante la marcha según los necesites, como yo lo hice.

6. Configurando git aliases

Algo que percibí, es que al usar linux alias para comandos git, me limitaban a poder usarlos solo en ambientes linux, y debido a que aveces suelo usar git en windows;
Basándome en los alias que tiene el plugin Git de oh-my-zsh, decidí configurar esos alias dentro de mi configuración de git como aliases. Ademas con el objetivo de aprenderlos, me obligue a crear solo los que necesitaba y usara de forma repetida, ya luego iría agregando nuevos según los necesite.

Para crear un alias en git, puedes usar un comando como este:

git config --global alias.[alias_comando] [comando_git]

alias.[alias_comando] [comando_git] le dice a git que agregue esta abreviación para un comando especifico en la sección [alias] del archivo de configuración de git .gitconfig.

Esto lo hará ya sea de forma local o global, en este caso el argumento —global nos dice que queremos que sea global, es decir que este disponible para todos los repositorios en nuestro sistema. Pero si lo quitamos este sera configurado localmente en un solo repositorio.

Por ejemplo crearemos el git aliases del comando status, escribiendo lo siguiente en nuestro terminal:

#global
git config --global alias.st status

#local
git config alias.st status

Estas lineas nos dice que la abreviación al comando status ahora sera st

El archivo .gitconfig lo podemos encontrar en las siguientes ubicaciones:

• Si la instalación que se realizo fue para uso global de todos los usuarios, estará:

  • Windows: 'C:\Users<username>.gitconfig

  • Linux/Ubuntu: ~home<username>.gitconfig

• Si lo queremos hacer solo para un repositorio o de forma local, cada repositorio git tiene una carpeta .git que suele estar oculta, al ingresar a esta carpeta puedes encontrar el archivo de configuración .gitconfig.

Si deseamos configurar varios alias a la vez, abrimos el fichero .gitconfig ya sea global o local y bajo la sección [alias] empezamos a crear o editar nuestros alias para comandos de git.

De esta forma puedes crear los alias que mas te gusten. Lo mas recomendable es que crees los que uses mas a menudo y según tus necesidades, ya queda al alcance de tu imaginación.

Listar tus git aliases configurados

Puedes tener un alias, que te muestre un listado de todos tus alias configurados, para crearlo escribe la siguiente línea en tu terminal:

git config --global alias.alias "! git config --get-regexp ^alias\. | sed -e s/^alias\.// -e s/\ /\ =\ /"

Luego para probarlo, escribe git alias en tu terminal y veras como se listan todos los git aliases que configuraste:

7. Usando nuestros "alias"

Para probar los nuevos alias configurados, crearemos un nuevo repositorio. Entonces, dentro de un nuevo directorio con el nombre que prefieras, abrimos un terminal y ejecutamos el comando g init o git init para inicializar el repositorio. como puedes ver usamos el linux alias g

Ahora podemos crear archivos dentro del repositorio, y para añadirlos al staging area con un git add <archivo> o en nuestro caso el comando abreviado g add README.md.

Si hacemos un g st o git status, nos damos cuenta que los archivos están listos para ser "commiteados/versionados" o registrados en el log del repositorio. como puedes ver ahora usamos la combinación de linux alias y git aliases

8. Usando commitizen para escribir buenos mensajes de commit

Para hacer commit de tus cambios, escribes git commit, o si usamos nuestros alias configurados escribiríamos g commit o g c, al hacerlo se abrirá un editor donde describirás tu mensaje commit.

Pero, esto podría ser un poco molesto, si existe una herramienta llamada commitizen, que mejora la experiencia al escribir commits y de paso le añade convenciones de buenas prácticas.

Al usar commitizen a través de su CLI, en lugar de escribir el comando git commit podemos usar el comando cz y solo escribiendo en nuestro terminal git cz, g cz o simplemente cz, commitizen reconocerá este comando y lanzara una pequeña app cli, que de manera interactiva, nos guiará para completar y escribir nuestro mensaje de commit. Podemos ver un ejemplo en la imagen siguiente.

Haciendo nuestro repositorio commitizen friendly

Antes de poder usar las ventajas de commitizen, debemos configurar nuestro repositorio y hacerlo Commitizen friendly como lo llaman los creadores. Esto lo hacemos escribiendo lo siguiente en nuestro terminal:

1. Instalamos el paquete npm escnpm install -g commitizen ,

2. Inicializamos un proyecto npm escribiendo npm init

3. Configuramos nuestro repositorio para usar cz-conventional-changelog adapter, escribiendo:

commitizen init cz-conventional-changelog --save-dev --save-exact

Esto agregara en el archivo package.json a commitizen como una dependencia de desarrollo.

Escribiendo un commit con Commitizen

Ahora estamos listos para hacer un commit usando commitizen.

Hacemos algún cambio en nuestro repositorio, agregamos dicho cambio con git add y luego escribimos g cz todo desde nuestra terminal.

1. Aparecerá un cli interactivo, que primero nos pedirá elegir el tipo de cambio que estamos realizando ya sea una nueva característica, cambio en documentación, corrección de errores, etc; tal como lo dicta la convención de conventional-commits en este caso al estar inicializando el repositorio osea es el primer commit, escogemos feat de feature.

1. Especificamos el scope del cambio, aqui escribiremos * u all ya que es la inicializacion de todo el repositorio.

1. Seguido a esto nos pide ingresar un mensaje corto para el commit, donde escribiremos commit inicial. Seguidamente nos pide agregar una descripción mas detallada para el commit, en este caso la podemos dejar en blanco.

1. Luego nos pregunta si hay breaking changes o cambios importantes, en este caso escribimos No o N. También nos pregunta si este cambio afecta algún issue o problema abierto donde podemos describirlo, en este caso escribimos No.

Al final se creara el commit con un mensaje que usa un formato con convenciones y buenas practicas feat(*): commit inicial , y esto con ayuda de commitizen.

Formateando mi git log en una sola linea (git aliases)

Si queremos ver como quedo nuestro mensaje commit, podemos escribir git log o g l si tenemos configurado un alias, para poder ver el historial de cambios de nuestro repositorio.

Te puede parecer curioso que el resultado de haber hecho git log en tu equipo no es igual al de la imagen anterior; para que tu git log este formateado en una sola linea y con colores, puedes crear y usar el alias para git pegando en tu terminal el comando a continuación.

git config --global alias.l "log --pretty=format:'%Cgreen%h %Creset%cd %Cblue[%cn] %Creset%s%C(yellow)%d%C(reset)' --graph --date=relative --decorate --all"

Entonces para usarlo debes escribir g l y tendrás un resultado parecido.

En internet encuentras mucha información, sobre modelos y colores del formato en el que se muestra tu git log, su forma de personalizar es muy flexible y con muchas alternativas según tu Sistema Operativo.

Formateando y detallando mi git log (git aliases)

Tengo configurado un alias diferente también para el comando git log, pero que muestra mas a detalle los archivos ue fueron modificados en cada commit, para eso escribe el siguiente comando en tu terminal:

git config --global alias.ll "log --graph --name-status --pretty=format:'%C(red)%h %C(reset)(%cd) %C(green)%an %Creset%s %C(yellow)%d%Creset' --date=relative"

Entonces si ejecuto g ll o git ll, obtengo lo siguiente (este es el log de otro repositorio para fines demostrativos):

9. Conclusion

Puedes estar pensando, que tal vez no vale la pena instalar y depender de una librería solo para escribir un commit. Pero como en todo, eso depende:

• de tus necesidades

• de si quieras escribir buenos commits siguiendo una convención.

• ya conoces de memoria la convención Conventional-commits y no necesitas una herramienta

• usas tu propia convención con emojis en tus mensajes de commits

• etc..

Pueden ser muchos puntos de vista, y puede ser que no estes de acuerdo con el mio.

Todo lo compartido en esta lectura, bien o mal, es simplemente mi experiencia, mi gusto y la forma en que a mi me ha funcionado.

Ten por seguro que existen muchas mas formas de hacerlo, e incluso puede que sean mejores; al final el objetivo de todo este proceso, es poner en evidencia la importancia de tener una buena narrativa de tu historial de cambios en tu repositorio, y esto lo logras escribiendo buenos mensajes de commit desde el principio.

Mi recomendación, es que empieces a usar commitizen en repositorios en los que trabajes de forma individual y siempre al iniciar el repositorio. Si lo vas a usar en un repositorio de equipo, es mejor que el equipo se ponga de acuerdo y dejen claro que se usara una convención y linter de commits, esto les dará muchas ventajas a futuro y menos desacuerdos.

Bueno, eso es todo, Muchas gracias por llegar hasta el final!! ✌, espero haya sido de tu interés, y de ayuda.

Te invito a que pruebes commitizen y que configures tus propios alias, ademas de que juegues con el formato de resultado de algunos comandos.

Eres libre de revisar mis Dotfiles y darme tu opinion, tengo algunas cosas nuevas que descubrí y que estoy probando.

Si tienes alguna duda o feedback sobre este contenido no dudes en hacérmelo saber.

• 📧 apalaciosg91@gmail.com

• 👨🏽‍💻GitHub: rpalaciosg

• 🐦Twitter: rpalaciosg_

• 💼LinkedIn: richardpalaciosgarcia

10. Recursos

• https://git.wiki.kernel.org/index.php/Aliases#Use_graphviz_for_display

• https://jasonm23.github.io/oh-my-git-aliases.html

• https://github.com/craftzdog/dotfiles-public

• https://unsplash.com/photos/91AQt9p4Mo8

• https://www.conventionalcommits.org/en/v1.0.0/

• https://github.com/commitizen-tools/commitizen

• Imágenes almacenadas en imgur a traves de https://hackmd.io/