Convenciones nomenclatura de URL en Web APIs

Si está creando tu propia API REST, debes estar familiarizado con algunas de las mejores prácticas de la industria para nombrar los puntos finales de la API REST.

Es muy importante conocer las mejores prácticas para nombrar tus API RESTful. El uso de las convenciones de nomenclatura de la API REST reduce drásticamente la curva de aprendizaje y facilita que los nuevos desarrolladores y usuarios de terceros comiencen con la API. Cuantas más personas entiendan cómo usar los métodos adecuados, más fácil será para todos. Estos estándares deberían ser necesarios para cada proceso de denominación de URI.

¿Qué es la URL?

Una URL es un tipo específico de URI que incluye la ubicación de un recurso y el protocolo utilizado para acceder a él.

Puede ser dividida en varias partes:

scheme:// authority path ? query # fragment

1. Esquema: El esquema es la primera parte de la URL e indica el protocolo utilizado para acceder al recurso. Ejemplos comunes incluyen «http», «https», «ftp», «archivo» y «datos».
2. Autoridad: La autoridad es la parte de la URI que identifica el recurso específico. Típicamente incluye el nombre de dominio o la dirección IP del servidor que aloja el recurso y el número de puerto utilizado para acceder a él. Por ejemplo, en la URI «http://www.ejemplo.com«, la autoridad es «www.ejemplo.com«.
   1. Host: El host es el nombre de dominio o la dirección IP del servidor que aloja el recurso. Por lo general, viene después del esquema y está separado por «://» (doble diagonal). Por ejemplo, en la URL «http://www.ejemplo.com«, el host es «www.ejemplo.com«.
   2. Puerto: El puerto es el número utilizado para acceder al recurso en el servidor. Es opcional y viene después del host separado por «:» (dos puntos). Por ejemplo, en la URL «http://www.ejemplo.com:8080«, el puerto es «8080».
3. Ruta: La ruta es la parte de la URL que sigue al host y al puerto y se utiliza para identificar la ubicación específica del recurso en el servidor. Puede incluir barras diagonales «/» para indicar subdirectorios. Por ejemplo, en la URL «http://www.ejemplo.com/acerca«, la ruta es «/acerca».
4. Consulta: La consulta es la parte de la URL que viene después de la ruta y se utiliza para enviar información adicional al servidor. Por lo general, está separada de la ruta por un signo de interrogación «?». Por ejemplo, en la URL «http://www.ejemplo.com/buscar?q=ejemplo«, la consulta es «q=ejemplo».
5. Fragmento: El fragmento es la última parte de la URL y se utiliza para identificar una sección específica del recurso. Está separado del resto de la URL por un símbolo «#». Por ejemplo, en la URL «http://www.ejemplo.com/acerca#historia«, el fragmento es «historia».

Es importante tener en cuenta que no todas las URLs incluyen todas estas partes. Algunas URLs solo pueden incluir un esquema, un host y una ruta, mientras que otras pueden incluir todas las anteriores.

Convenciones nomenclatura de URL en API REST

Cuando se diseñan las URLs para una API REST, es una buena práctica seguir estas convenciones de nomenclatura:

• Usa sustantivos para nombrar URI: Utilice nombres para representar recursos en lugar de verbos.

http://www.ejemplo.com/usuarios //si
http://www.ejemplo.com/obtenerUsuarios //no

• Usa plural y singular: Utilice nombres en plural para colecciones de recursos y nombres en singular para recursos individuales.

http://www.ejemplo.com/usuarios //colección
http://www.ejemplo.com/usuario //usuario específico.

• Usa barras diagonales para indicar la jerarquía de URI: Utilice una barra diagonal «/» para separar los diferentes niveles de la jerarquía de recursos.

http://www.ejemplo.com/usuarios/{idUsuario}/pedidos //para indicar que los pedidos pertenecen a un usuario específico

• Separar palabras con guiones y en minúscula: Utilice letras minúsculas y guiones para separar palabras.

http://www.ejemplo.com/usuarios/{idUsuario}/pedidos-pendientes //si
http://www.ejemplo.com/usuarios/{idUsuario}/PedidosPendientes //no

• Usa parámetros de ruta: Utilice parámetros de ruta para identificar recursos específicos.

http://www.ejemplo.com/usuarios/{idUsuario} //para identificar un usuario específico.

• Usa parámetros de consulta: Utilice parámetros de consulta para filtrar o ordenar recursos.

http://www.ejemplo.com/usuarios?nombre=juan&orden=ascendente

• Usa verbos HTTP para indicar la acción a realizar en un recurso. Por ejemplo, utilice GET para recuperar un recurso, POST para crear uno, PUT para actualizarlo y DELETE para eliminarlo.
• Evite las extensiones de archivo.

http://www.ejemplo.com/usuarios.xml //no
http://www.ejemplo.com/usuarios //si

Conclusión

Es importante mantener las URLs sencillas y consistentes para que sean fáciles de entender, recordar y utilizar. Además, es recomendable seguir las convenciones existentes en la industria para garantizar la compatibilidad y la interoperabilidad con otros sistemas.