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 método en la API.
Agregar método
Los métodos definen la acción que se realizará sobre un determinado recurso.
Como primer paso debe seleccionar la opción de Agregar método en la versión de la API:
Si ya tienes métodos agregados, deberás hacer clic sobre el botón Agregar método.
Al agregar un método, como primer paso deberás seleccionar una vista de datos.
Recuerda que la vista de datos se relaciona a un origen de datos, y ejecuta acciones de lectura o escritura sobre ese origen.
Detalles del método
En el detalle del método deberás definir las configuraciones del método, esto es, cómo será la solicitud que deberá realizarse y cuál será la respuesta, además de otras configuraciones.
Tipo de solicitud
Define el tipo de solicitud o llamada: GET, POST, PUT, PATCH o DELETE.
Si tienes dudas sobre los tipos de solicitud consulta el artículo Qué son los tipos de solicitud de los métodos
Ruta del método
Define la ruta al método que describa la entidad o recurso que está siendo utilizado. Sugerimos que leas Cómo 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:
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:
/users/{id}
En esta caso, la
consulta a la API tendrá la siguiente estructura: http://api.vor-tex.io/accounts/v1/users/{id}.json
Descripción
Ingresa un texto que describa los datos y la acción del método.
Parámetros
Si la vista de datos tiene parámetros se mostrarán en pantalla.
Puedes Configurar variables de contexto para relacionarlas a los parámetros.
Recuerda que los parámetros, su valor por defecto y formato o reglas de validación se configuran en la vista de datos.
Plantillas de output
Las plantillas de saluda o output permiten definir el formato de respuesta del método. Puede además agregar múltiples formatos de salida, para ajustarse a diferentes estándares y/o facilitar las lectura de las respuestas por los sistemas, aplicaciones o usuarios consumidores.
Para encontrar mas información acerca de como configurar la salida de los métodos recomendamos leer:
- Cómo trabajar con las plantillas para definir la salida de los métodos
- Cómo definir formatos de salida de los métodos
Plantillas de error
Cuando la solicitud al método no sea exitosa, aplican las plantillas de error. Estas plantillas permiten definir errores personalizados de cada uno de los métodos.
Vista previa del output
La vista previa le permitirá conocer cuál será la respuesta del método, en base a la vista de datos, el formato y la plantilla seleccionados.
Diccionario de datos
El diccionario de datos permite entregar más información acerca de los atributos del método. Para cada una de las columnas de la vista es posible definir un Nombre, Descripción y Tipo de dato.
Los tipos de datos disponibles son string, integer, number y boolean.
Cuando defina tipos de dato numéricos ( integer y number) se habilitarán opciones extendidas de la API que permitirán realizar operaciones de agrupación y agregación (suma, promedio, conteo) y filtros dinámicos. Al agregar un diccionario estas opciones se mostrarán en la ventana Probar método del Portal del desarrollador.
El usuario desarrollador podrá consultar el diccionario de datos en el portal y mediante una solicitud de la API, aplicando .dict en la solicitud. Por ejemplo, https://api.empresa.com/api/v1/documentos.dict
Límites
Los límites pueden establecerse de manera global en la API y sobreescribirse en los métodos, para un control más preciso y diferenciado.
Privacidad del método
Permite configurar la privacidad del método. Sugerimos leer el artículo Configurar privacidad de APIs y métodos
Puede configurar el envío de la auth_key como parámetro o como cabecera.
Si selecciona como parámetro, la auth_key deberá ir en el endpoint de la solicitud, por ejemplo http://api.company.com/accounts/v1/users.json? auth_key=XXXXXXX
Si selecciona como cabecera, el envío de la auth key deberá enviarlo en el header con el nombre "Authorization" y su vaor.