Header Ads Widget

Ticker

6/recent/ticker-posts

Más de 10 prácticas recomendadas para nombrar puntos finales de API

 


Hay muchas razones para nombrar cuidadosamente los puntos finales de la API. La elección de nombres razonables para los puntos finales de API puede suavizar drásticamente la curva de aprendizaje de los nuevos desarrolladores, ayudándoles a saber intuitivamente qué buscar y dónde encontrarlo. Con eso en mente, dedicamos este artículo a más de diez de las mejores prácticas y convenciones más efectivas para nombrar puntos finales de API . Primero, discutiremos algunos principios de nomenclatura de recursos específicos de REST y luego pasaremos a algunas pautas más universales.

Convenciones de nomenclatura de recursos RESTful

Comencemos examinando algunas convenciones de nomenclatura específicas de REST . Si bien es posible que algunas de estas prácticas de nomenclatura se apliquen a otros estilos de diseño de API, se ven más comúnmente en la nomenclatura de los "puntos finales" de la API RESTful.

Descargo de responsabilidad: según el propio Roy Fielding , no existe un "punto final REST". Sin embargo, en el lenguaje común, los recursos se consideran un subconjunto de puntos finales .

URI como recursos como sustantivos

Una de las características más reconocibles de REST es el uso predominante de sustantivos en los URI. Los URI RESTful no deben indicar ningún tipo de funcionalidad CRUD (Crear, Leer, Actualizar, Eliminar). En cambio, las API REST deberían permitirle manipular un recurso, que debería tomar la forma de un sustantivo, a través de uno de los principales métodos HTTP .

Ejemplo: en /users/{id} lugar de/getUser

"Los URI RESTful deben referirse a un recurso que es una cosa (sustantivo) en lugar de referirse a una acción (verbo) porque los sustantivos tienen propiedades que los verbos no tienen, similar a los recursos que tienen atributos". RESTfulAPI.net

Recursos pluralizados

El siguiente paso es la cuestión de si los nombres de los recursos deben estar pluralizados. Es cierto que esto es una cuestión de preferencia; sin embargo, la mayoría de los expertos en diseño de API le recomendarían pluralizar todos los recursos a menos que sean recursos únicos.

Ejemplo: /users (recurso típico) o /users/{id}/address(recurso singleton)

Barras diagonales para jerarquía

Como se muestra en los ejemplos anteriores, las barras inclinadas se utilizan convencionalmente para mostrar la jerarquía entre recursos individuales y colecciones.

Ejemplo: /users/{id}/address claramente se incluye en el /users/{id}recurso que se incluye en la /userscolección.

“No existen reglas estrictas y rápidas [para la jerarquía], solo asegúrese de que la estructura impuesta tenga sentido para los consumidores de sus servicios. Como ocurre con todo en el oficio del desarrollo de software, el nombramiento es fundamental para el éxito ". RESTAPITutorial.com

Puntuación para listas

Cuando no existe una relación jerárquica (como en las listas), se deben utilizar signos de puntuación como el punto y coma o, más frecuentemente, la coma.

Ejemplo: /users/{id1},{id2} para acceder a varios recursos de usuario

Consultar parámetros cuando sea necesario

Para ordenar o filtrar una colección, una API REST debe permitir que se pasen parámetros de consulta en el URI.

Ejemplo: /users?location=USA para encontrar todos los usuarios que viven en Estados Unidos

Letras minúsculas y guiones

Por convención, los nombres de los recursos deben usar exclusivamente letras minúsculas. De manera similar, los guiones (-) se usan convencionalmente en lugar de los guiones bajos (_).

Ejemplo: en /users/{id}/pending-orders lugar de/users/{id}/Pending_Orders

Prácticas recomendadas generales para la denominación de endpoints

Las convenciones de nomenclatura anteriores suelen estar asociadas con las API REST. Sin embargo, hay un buen puñado de convenciones generales de nomenclatura a las que debe ceñirse independientemente de si su API es RESTful o no. Éstos son solo algunos de ellos:

inglés americano

Cíñete a usar el inglés americano para los nombres de tus endpoints / recursos, ya que es el dialecto con el que tu audiencia internacional de desarrolladores probablemente esté más familiarizada. La excepción a esto sería si su API se dirige a una audiencia nacional específica que usa predominantemente un dialecto diferente (por ejemplo, británico o australiano).

Ejemplo: en /airplanes lugar de/aeroplanes

Nombres intuitivos (sin jerga)

¡Haga sus nombres intuitivos! Siempre que sea posible, elija la palabra más simple y de uso más común para referirse a un concepto dado. Si se hace correctamente, la mayoría de todos los nombres de puntos finales / recursos deberían ser adivinables, lo que evita que los desarrolladores tengan que buscar en su documentación.

Como una extensión de esto, evite usar jerga. Los desarrolladores más expertos no tendrán problemas para adivinar la variante más simple de una palabra, ¡pero el desarrollador promedio no podrá adivinar un término técnico que no haya escuchado antes!

Ejemplo: en /users/{id}/card-number lugar de/users/{id}/pan

Hablando sobre las prácticas de nomenclatura para las API, en nuestra Cumbre de plataformas de 2019, Rahul Dighe recomendó una jerga menos centrada en el dominio. “Algo que es común y más comprensible hará que sus API sean mucho más utilizables”, dijo Dighe.

Sin resumir

Evite abreviar los nombres de los puntos finales / recursos. Con la tecnología moderna, realmente no hay necesidad. De hecho, los nombres abreviados pueden crear confusión en su API, ya que los desarrolladores luchan por adivinar (y a veces comprender) los nombres que ha elegido.

Ejemplo: en /users/{id}/phone-number lugar de/users/{id}/tel-no

Sin extensiones de archivo

Deje las extensiones de archivo (como .xml) fuera de sus URI. Lamentamos decirlo, pero son feos y añaden longitud a los URI. Si necesita especificar el formato del cuerpo, use el Content-Typeencabezado.

Ejemplo: en /users/{id}/pending-orders lugar de/users/{id}/pending-orders.xml

Sin barra inclinada hacia adelante

De manera similar, con el fin de mantener limpios los URI, no agregue una barra diagonal al final de los URI.

Ejemplo: en /users/{id}/pending-orders lugar de/users/{id}/pending-orders/

“La barra inclinada final no debe tener semántica específica. Las rutas de recursos deben ofrecer los mismos resultados, tengan o no la barra al final ".

¡La consistencia es clave!

La coherencia es un principio de nomenclatura de puntos finales que merece un reconocimiento especial. No importa qué tan de cerca siga nuestras sugerencias anteriores, su API siempre se sentirá torpe si los nombres son inconsistentes. Utilice siempre los mismos nombres para referirse a un concepto determinado dentro de su API.

Tenga en cuenta que esta guía es simplemente una compilación sugerida de las mejores prácticas de nomenclatura de puntos finales, y otras pueden adoptar variantes en la práctica. Lo más importante es que cualquier estilo que adopte debe aplicarse universalmente. Del mismo modo, asegúrese de que los nombres de los puntos finales sean coherentes con los nombres utilizados en la documentación y, si corresponde, en la propia aplicación.

Ejemplo: /users debe documentarse bajo el usersrecurso en lugar del getUsermétodo

Pensamientos finales

Ahí lo tiene: un puñado de las convenciones y mejores prácticas más influyentes para nombrar puntos finales de API, RESTful y de otro tipo. Desde los problemas más técnicos, como mostrar la jerarquía de recursos, hasta los más lingüísticos, como el uso del inglés americano, esta colección concisa de principios de nomenclatura seguramente complacerá incluso a los desarrolladores más estrictos. Para convenciones de diseño de API más detalladas, recomendamos el libro de estilo de API seleccionado por API Handyman. Tiene mucha información de calidad, mostrando guías de estilo de diseño de API de muchas empresas.

Publicar un comentario

0 Comentarios