Cómo definir las rutas a los métodos: buenas prácticas

Cómo definir las rutas a los métodos: buenas prácticas

Resumen

La definición de rutas o paths debe ser consistente con los recursos o entidades a los que refiere el método.

A continuación se indican ciertas buenas prácticas para considerar en la definición de rutas.


Un repaso

Antes de continuar, repasemos cuáles son las partes de un endpoint o url de una API. A modo de ejemplo:
  1. "api" es el subdominio de consulta a la API.
  2. "empresa.com" es el dominio de su cuenta.
  3. "indicadores-diarios" es el nombre de la API. Recuerde que el nombre de la API será el título que defina al momento de crear la API.
  4. "v1" es la versión de la API. Revise el artículo sobre versiones de APIs.
  5. "dolar" es el nombre del método de la API.
  6. ".json" es el formato de consulta al método. Revise el artículo sobre formatos de salida.
  7. Lo que sigue al signo de interrogación "?" son los parámetros que debrán enviarse, como la auth_key u otros que requiera el método.

Definición del idioma

Defina un idioma a utilizar para sus APIs y métodos. Recomendamos utilizar español si es su idioma primario, pero también puede utilizar inglés. Lo relevante en este caso es ser consistente, debe utilizarse siempre el mismo idioma para las APIs, métodos, nombres de parámetros, atributos, diccionarios, etc.

Ruta del método

Al momento de crear un método, deberá definir su ruta.



  1. Utilice sustantivos en plural, no verbos.
  2. Evite utilizar sustantivos en singular.
  3. Utilice las mismas rutas para diferentes tipos de solicitud.
  4. No utilice acentos, espacios ni caracteres especiales en la URL.
  5. Si desea separar palabras utilice el guión medio.

Ejemplos correctos

Obtener listado de documentos en formato .json:
  1. GET  https://api.empresa.com/api/v1/documentos.json

Obtener documentos según identificador en formato .json:
  1. GET  https://api.empresa.com/api/v1/documentos/123.json

Crear documentos
  1. POST https://api.empresa.com/api/v1/documentos.json

Ejemplos incorrectos

Los sustantivos en singular no se recomiendan:
  1. GET https://api.empresa.com/api/v1/documentos
  2. GET  https://api.empresa.com/api/v1/documento/123.json
Verbos en la URL
  1. POST https://ejemplo.cl/api/v1/solicitud/crear

Parámetros en la ruta

En caso que lo requiera, puede agregar los parámetros de la la vista de datos en la ruta del método.

Por defecto, el método hereda los parámetros de su vista asociada. Por ejemplo:
  1. http://api.empresa.com/accounts/v1/users.json?auth_key=XXXXXXX&id=16329928

Pero también es posible agregar un parámetro en la ruta del método. Para ello, debe ingresarse en la ruta al método en nombre del parámetro entre llaves.
Por ejemplo:
  1. /users/{id}
En esta caso, la consulta a la API tendrá la siguiente estructura:
  1. http://api.empresa.com/accounts/v1/users/123.json?auth_key=XXXXXXX