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

    • Related Articles

    • Cómo definir formatos de respuesta de los métodos

      Resumen Los formatos de salida permiten definir uno o más formatos de respuesta en los métodos de su API. Los formatos de salida pueden ser mútiples en formato JSON, aunque también puede exponer los datos en CSV y XML. Configurar formatos Al crear un ...

    • Crear métodos de APIs

      Resumen En el articulo Crear y gestionar versiones de APIs se mostraron los primeros pasos necearios para crear APIs. Los métodos definen la acción que se realizará sobre un determinado recurso. Como primer paso debe seleccionar la opción de Agregar ...

    • Cómo definir respuestas de error personalizadas

      Resumen Así como puedes definir formatos y plantillas para las respuestas exitosas de la solicitud al método, puedes definir plantillas de error para cada formato que hayas agregado y para cada tipo de error conocido. Configurar plantillas de error ...

    • Qué son los tipos de solicitud de los métodos

      Resumen Los métodos de APIs requieren la definición de un tipo de solicitud. Sugerimos que respete los estádares REST/json al crear sus métodos, en base a las siguientes definiciones. Tipos de petición o solicitud Los métodos más utilizados en las ...

    • Configurar privacidad de APIs y métodos

      Resumen Puedes definir la privacidad de tus APIs y métodos para otorgar acceso solo a los usuarios que desees, o revocar los accesos cuando lo requieras. Reglas de privacidad Puedes configurar la visibilidad de las APIs y los métodos, es decir, si ...