Crear métodos de APIs
Resumen
Los métodos definen la acción que se realiza sobre un recurso de la API: una vista de datos o un pipeline, expuestos en una URL del gateway. En el artículo Crear y gestionar versiones de APIs se mostraron los primeros pasos para crear una API. Aquí ve cómo agregar un método a una versión, configurarlo, guardarlo, publicar la versión y llamarlo por el gateway.
Antes de comenzar
- Necesita una API con al menos una versión y una vista de datos o un pipeline publicados. Recuerde que la vista se relaciona con un origen de datos y ejecuta acciones de lectura o escritura sobre él.
Agregar un método
Seleccionar el recurso
En la ficha de la API, dentro de la versión, haga clic en Agregar método. Si ya tiene métodos agregados, el botón está al final del listado.
Como primer paso, seleccione el recurso que el método va a exponer: una vista de datos o un pipeline publicados.
Detalles del método
En el detalle del método define cómo será la solicitud, cuál será la respuesta y otras configuraciones.
Tipo de solicitud
Defina el tipo de solicitud o llamada: GET, POST, PUT, PATCH o DELETE. Si tiene dudas, consulte Qué son los tipos de solicitud de los métodos.
Ruta del método
Defina la ruta al método con un nombre que describa la entidad o recurso, por ejemplo empleados. La URL completa se arma sola con el dominio de la API, el nombre de la API, la versión, la ruta y el formato: https://api.example.com/demo-ventas/v1/empleados.json. Sugerimos leer Definir las rutas a los métodos: buenas prácticas.
Por defecto, el método hereda los parámetros de su vista asociada, por ejemplo https://api.example.com/accounts/v1/users.json?auth_key=YOUR_AUTH_KEY&id=16329928. También puede poner un parámetro en la ruta, escribiendo su nombre entre llaves: con la ruta /users/{id}, la consulta tiene la forma https://api.example.com/accounts/v1/users/{id}.json.
Descripción
Ingrese un texto que describa los datos y la acción del método. Se muestra en la documentación del portal para desarrolladores.
Parámetros
Si la vista de datos tiene parámetros, se muestran en pantalla. Con Configurar puede relacionarlos con variables de contexto, encriptarlos o enviarlos como cabecera.
Plantillas de output
Las plantillas de salida u output definen el formato de respuesta del método. Puede agregar múltiples formatos de salida para ajustarse a distintos estándares o facilitar la lectura por parte de los sistemas y usuarios consumidores. Para más información, lea Cómo trabajar con las plantillas para definir la salida de los métodos y Definir formatos de respuesta de los métodos.
Plantillas de error
Cuando la solicitud al método no es exitosa, aplican las plantillas de error. Permiten definir errores personalizados para cada formato del método.
Vista previa del output
La vista previa le muestra cuál será la respuesta del método, en base a la vista de datos, el formato y la plantilla seleccionados.
Datos de prueba
Debajo de la vista previa, Cargar Datos de Prueba abre una tabla con una columna por cada campo de la vista para que escriba hasta tres filas de ejemplo; cada celda toma el tipo de la columna. Al Guardar, la vista previa se arma con esas filas en lugar de ejecutar la vista real y lo indica con el aviso Usando datos de prueba para la vista previa. En el portal para desarrolladores, la vista previa de la ficha del método también usa estos datos. Sirven para diseñar la plantilla de salida sin consultar el origen, por ejemplo cuando todavía no tiene datos o cuando cada consulta es costosa.
Los datos de prueba no salen del editor: Probar método en el portal y las llamadas por el gateway siempre ejecutan la vista real. Se borran si cambia la vista del método, y Limpiar Datos de Prueba los quita a mano. En un método sobre un origen de escritura, en lugar de la tabla se pide un JSON con el resultado de la escritura simulada.
Diccionario de datos
El diccionario de datos entrega más información sobre los atributos del método. Para cada columna de la vista puede definir un nombre, una descripción y un tipo de dato: string, integer, number o boolean. El desarrollador lo consulta en el portal o con .dict en la solicitud, por ejemplo https://api.example.com/api/v1/documentos.dict.
Cuando define tipos de dato numéricos (integer y number) se habilitan opciones extendidas de la API: agrupación, agregación (suma, promedio, conteo) y filtros dinámicos, que aparecen en la ventana Probar método del portal.
Límites
Los límites se establecen de manera global en la API y pueden sobreescribirse en cada método, para un control más preciso. Lea Configurar límites en métodos (rate limit).
Privacidad del método
Permite configurar si el método es público o privado. Sugerimos leer Configurar privacidad de APIs y métodos. Puede configurar el envío de la auth_key como parámetro, en la URL (?auth_key=YOUR_AUTH_KEY), o como cabecera, en el header Authorization.
Guardar y publicar
Guardar el método
Haga clic en Guardar. Vuelve a la ficha de la API, con el método listado en la versión.
Publicar la versión
Haga clic en Publicar en la versión de la API. Recién entonces el método responde en el gateway y aparece en el portal para desarrolladores. Puede probarlo con una llamada como esta:
curl "https://api.example.com/demo-ventas/v1/empleados.json?auth_key=YOUR_AUTH_KEY"
Resultado esperado
El método aparece en la versión de la API con su tipo de solicitud y su ruta. Una vez publicada la versión, la URL responde con los datos de la vista en el formato elegido, y el método figura en el catálogo del portal con su documentación.
Errores frecuentes
- La vista no aparece en el selector: no está publicada. Publique la vista o el pipeline y vuelva a agregar el método.
- La URL devuelve un error de recurso no encontrado: la versión no está publicada, o la ruta o el formato no coinciden con los configurados.
- La vista previa no carga: el origen de datos no responde. Revise la ficha de la vista.