Convenciones de nombres en API Rest

Diseñar una API RESTful no se trata solo de crear un montón de endpoints con nombres aleatorios. REST, o Representational State Transfer, es una arquitectura compleja que se basa en dividir una API en recursos lógicos a los que se puede acceder a través de métodos HTTP estándar como GET, POST, PUT y DELETE.

En una API RESTful, un recurso es cualquier cosa que se pueda nombrar, direccionar y representar. Los recursos pueden ser cualquier cosa, desde objetos hasta documentos, y pueden identificarse mediante un URI único. Todo en una API RESTful es un recurso, y se puede acceder a cada recurso a través de su propia URL.

Entonces, ¿cómo afecta esto la forma en que nombramos nuestros métodos en una API RESTful? Bueno, todo en una API RESTful gira en torno a los recursos, por lo que tiene sentido que los métodos que usamos para interactuar con esos recursos se nombren de acuerdo con cómo queremos acceder a ellos o manipularlos. Por ejemplo, si desea recuperar un recurso específico, debe usar una solicitud GET con la URL del recurso. Si desea crear un nuevo recurso, debe usar una solicitud POST con la URL de la colección que contendrá el nuevo recurso.

En general, seguir las convenciones de nombres en API REST es fundamental para garantizar la coherencia y facilitar a los desarrolladores la comprensión de cómo interactuar con la API. Al apegarse a los métodos HTTP estándar y las convenciones de nomenclatura, puede asegurarse de que su API sea fácil de usar y comprender para los desarrolladores internos y externos.

Entendiendo la estructura de las URL en una API REST

La estructura de URL es un aspecto crucial de cualquier API REST. Ayuda al cliente a comprender cómo interactuar con la API y acceder a los recursos. Las API REST usan verbos HTTP, como GET, POST, PUT y DELETE, para realizar operaciones en los recursos. Una URL generalmente consta de un dominio, un número de versión, una ruta de recursos y parámetros de consulta opcionales.

Una razón para crear versiones de una API a través de URL es garantizar que sus usuarios siempre tengan acceso a una versión coherente de su API. Por ejemplo, puede usar «/api/v1/» para indicar la primera versión de la API y «/api/v2/» para indicar la próxima versión. De esta manera, cuando realice cambios en su API, sus usuarios pueden continuar usando la versión anterior hasta que estén listos para migrar a la nueva versión.

Otro aspecto a considerar es la elección entre usar guiones, guiones bajos o camelCase para separar palabras en la ruta de la URL. Se recomienda ceñirse a los guiones al crear URL para evitar confusiones o incoherencias al solicitar diferentes recursos.

Ejemplos:

GET /api/v1/users/123

PUT /api/v2/users/123

Usar sustantivos para nombrar recursos

Al nombrar recursos en una API REST, es importante usar sustantivos sobre verbos. La razón es que los recursos representan datos e información, mientras que los verbos representan acciones. Los sustantivos proporcionan una representación clara de la estructura de datos y la información que se comparte. Además, los recursos se pueden reutilizar entre endpoints, mientras que verbos como «crear», «obtener» y «actualizar» no se pueden compartir y se deben volver a crear para cada endpoint.

El uso de verbos como parte de las convenciones de nombres en API Rest puede hacer que a los clientes les resulte confuso identificar los recursos necesarios y las acciones correspondientes. Por lo tanto, es necesario garantizar la coherencia y la claridad mediante el uso de sustantivos que describan con precisión los recursos a los que se accede.

Ejemplos:

GET /api/v1/users/123

GET /api/v1/products/456

Usar la forma plural para nombrar recursos

Una de las prácticas estándar para nombrar recursos en una API REST es usar la forma plural. El razonamiento detrás de esto es indicar que la API está recuperando una colección de recursos y el endpoint puede devolver varias instancias del recurso. La forma plural también hace que los endpoints sean más legibles por humanos y está más en línea con las convenciones de lenguaje natural.

El uso de la forma singular puede crear confusión al recuperar varias instancias de un recurso, ya que el usuario puede no estar seguro de si obtendrá una sola instancia o varias instancias. Además, al agregar nuevos recursos a la API, es más fácil agregar una nueva colección de recursos en lugar de un solo nombre de recurso.

También es importante garantizar la coherencia al nombrar los recursos intermedios, que pueden usarse para representar la relación padre-hijo entre los recursos. El uso de la forma plural para todos los recursos intermedios puede ayudar a mantener la coherencia en toda la API.

Ejemplos:

GET /api/v1/users

GET /api/v1/orders

Usar slashes para denotar jerarquias

El uso de barras o slash en la ruta de la URL puede ayudar a expresar la relación jerárquica entre los recursos. La barra tiene un significado particular en el diseño de la API REST, y usarla de la manera correcta puede hacer que su API sea mucho más intuitiva.

Agregar barras en la ruta de la URL generalmente representa una jerarquía, donde cada segmento de la URL representa un nivel de abstracción. Por ejemplo, se puede acceder a un recurso que representa comentarios para una publicación de blog en /publicaciones/1/comentarios, donde «publicaciones» es el recurso principal y «comentarios» es el recurso secundario.

También es importante comprender que el orden de los segmentos de URL y el anidamiento de las URL no necesariamente deben seguir la jerarquía de datos subyacente. La estructura debe tener sentido para el usuario y ser fácil de navegar.

Ejemplos:

GET /api/v1/users/123/orders

GET /api/v1/products/456/customers/789

Conclusión

Seguir las convenciones de nomenclatura estándar en el diseño de API REST es esencial para crear API claras, intuitivas y coherentes. Los beneficios de seguir estas convenciones son numerosos, incluido hacer que sus API sean más legibles por humanos, más fáciles de navegar y más fáciles de usar. Al adoptar convenciones estándar de la industria, puede reducir la confusión tanto para los desarrolladores como para los usuarios finales, lo que en última instancia conduce a tasas de adopción más altas y una mayor satisfacción general con su API. Independientemente de las convenciones específicas que elija, tomarse el tiempo para establecer un estándar de nomenclatura coherente beneficiará en gran medida sus esfuerzos de desarrollo de API a largo plazo.

Para poder aplicar estas convenciones, en el siguiente enlace te explicamos los primeros pasos en la creación de microservicios Spring Boot.

Te puede interesar