¿Estás configurando correctamente los puntos finales de la API REST?

¿Estás configurando correctamente los puntos finales de la API REST?

¿Estás configurando correctamente tus puntos finales de API? A menudo, cuando estamos configurando puntos finales para nuestras APIs, nos encontramos con situaciones en las que no estamos seguros de si escribir en forma plural o singular. ¿Deberíamos usar guiones bajos o guiones? ¿Cómo mencionar los IDs? Para una API que está creando un recurso, ¿deberíamos usar /recurso/crear? Y muchas más. Así que hagamos un análisis profundo sobre las convenciones de nombres para APIs REST. Aquí cubriremos:

• Puntos finales
• Métodos
• Versionado

Puntos finales

Comencemos revisando algunas convenciones de nombres para APIs REST.

Recursos como sustantivos

Las APIs REST deberían permitirte manipular un recurso utilizando uno de los principales métodos HTTP. Los URIs REST no deberían indicar ningún tipo de operaciones CRUD. Deberían referirse a un recurso en lugar de una acción/verbo. Siempre que sea posible, usa solo formas plurales de los sustantivos, a menos que sean recursos singleton.

Buenos ejemplos:

• https://api.website.com/v1/store/products
• https://api.website.com/v1/store/customers
• https://api.website.com/v1/store/discounts

Malos ejemplos:

• https://api.website.com/v1/store/createproducts
• https://api.website.com/v1/store/updatecustomers
• https://api.website.com/v1/store/getdiscounts

Jerarquía

La jerarquía entre recursos y colecciones se define mediante el uso de barras diagonales.

"Como en todo en el oficio del desarrollo de software, el nombrado es crítico para el éxito"

Buen ejemplo:

• https://api.website.com/v1/item/store

Mal ejemplo:

• https://api.website.com/v1/store/items

Guiones

Es ampliamente aceptado que leer guiones ( first-name ) es más claro y fácil de usar que leer guiones bajos ( first_name ). Por lo tanto, siempre que un punto final de API REST contenga múltiples palabras, es mejor usar guiones en lugar de guiones bajos. Además, hay un ángulo aquí desde el punto de vista del SEO también. Se recomienda usar guiones ya que ayuda a los bots a identificar los conceptos en la URL más fácilmente. Y un guion bajo entre dos palabras se considera como un todo una palabra, mientras que usar guiones se considera como dos palabras separadas.

Buen ejemplo:

• https://api.website.com/v1/store/inventory-management/active-orders

Mal ejemplo

• https://api.website.com/v1/store/inventory_management/active_orders

Métodos

Ahora sabemos que no deberíamos usar verbos en nuestros puntos finales de API REST, pero esto plantea la pregunta de cómo especificar el verbo entonces. Para esto, tenemos los métodos HTTP al rescate. Los métodos HTTP son los verbos que indican el tipo de operación que la API podría estar ejecutando.

Métodos HTTP:

• GET corresponde a la operación de "Lectura" de un recurso o una colección.
• POST corresponde a la operación de "Crear" de un recurso o una colección.
• PUT corresponde a la operación de "Actualizar" de un recurso o una colección.
• DELETE corresponde a la operación de "ELIMINAR" de un recurso o una colección.

Hay un total de 39 métodos HTTP, pero GET, POST, PUT y DELETE son los métodos más comúnmente usados y básicos. Cubriremos todos los métodos HTTP y sus casos de uso en un blog separado.

Versionado

Siempre es mejor versionar tus APIs. Las mismas URLs pueden ser consumidas sin tener que hacer cambios mayores en los puntos finales de la API REST. Los puntos finales de API nunca deberían ser invalidados, ya que esto podría tener consecuencias imprevistas para las aplicaciones que los consumen.

Ejemplos:

• https://api.website.com/v1/store/items
• https://api.webiste.com/v2/store/employees

Puntos clave

• Usa sustantivos para representar recursos.
• Evita usar verbos en los puntos finales de la API REST.
• No uses guiones bajos (`_`) en un punto final. En su lugar, usa guiones (`-`).
• Usa consultas para filtrar, ordenar o limitar una colección de API.
• Nunca agregues extensiones de archivo a las URLs. Si deseas especificar el tipo de contenido, usa el encabezado `Content-Type`.
• Siempre prefiere usar letras minúsculas en los puntos finales de la API REST.
• No pongas barras diagonales finales (`/`) en los puntos finales de las APIs REST. No añaden valor semántico y pueden ser confusos.
• Elige nombres simples. Si se hace correctamente, los puntos finales de API serán muy fáciles de recordar o adivinar para cualquier desarrollador.