Documentación de la ApiRest
¿Qués es la API Rest de Velneo vERP?
Todas las aplicaciones programadas con la plataforma de desarrollo Velneo, simplemente heredando vERP y sin necesidad de programar, pueden disponer de una API Rest para consumir sus datos y funcionalidades.
La API Rest de Velneo es segura, funciona con protocolo https, utiliza una API Key que puedes configurar, y para cada API Key puedes configurar qué tablas, búsquedas o procesos estarán disponibles. Incluso para cada tabla puedes indicar qué campos estarán visibles. También permite etablecer permisos por usuario.
La API Rest de Velneo está autodocumentado a través del servicio estándar Open API permitiendo a terceros usar tu API Rest, ya que está basada en el estándar json:api.
Existen dos versiones de la API Rest integradas en la plantilla: V1 y V2.
V1 es la versión que se usaba hasta la versión 33, que sigue el estándar Swagger, y que se mantiene por compatibilidad con desarrollos que la sigan usando.
V2 es una versión evolucionada para adaptarse al estándar OpenAPI y es la que se recomienda usar.
Si estás usando V1, te recomendamos que vayas adaptando tus desarrollos a V2 ya que dejará de estar soportado en futuras versiones de la plantilla.
¿Puedo usar esta API REST sin heredar o usar Velneo vERP?
Para poder usar la API Rest es necesario heredar vERP ya que hace uso de la tabla de usuarios (USR_M) que está relacionada, directa o indirectamente con un elevado número de tablas de plantilla y requeriría tenerlas todas replicadas en el programa donde se quisiese usar.
Ejecutar la aplicación y configurar la seguridad
La seguridad del API REST está basada en 2 capas actualmente:
Capa 1: clave API key.
Capa 2: configuración de seguridad a nivel de tablas, campos, procesos y búsquedas.
La capa 1 consiste en una clave definible por el programador o el usuario en tiempo de ejecución que se configura desde la opción API keys del menú Supervisor.
Al ejecutar esta opción se muestra el formulario de menú de API keys.
Podemos crear tantos registros como queramos.
Para crear una nueva API key debemos pulsar el botón + de la barra de herramientas de la rejilla.
En cada registro de API key debemos grabar una descripción y el valor de la clave del API key.
En la pestaña seguridad de la API key podremos generar tantos registros como tablas tenemos en nuestros proyectos de datos, más un registro para los objetos poder configurar la seguridad de los procesos que no tienen tabla destino declarada.
En el formulario se puede configurar con el check si es para procesos sin tabla destino, una vez marcado sólo nos aparecerá la pestaña de procesos:
En la parte superior tenemos 4 checks para configurar si este API key soporta los métodos GET, PUT, POST y DELETE.
En caso de no marcar el check sin tabla nos aparecerán 3 pestañas para configurar la seguridad de campos, procesos y búsquedas.
Para seleccionar un proceso, lo que debemos seleccionar en los combo boxes son el proyecto de datos donde está tabla de destino y la tabla de destino.
En el caso de configurar una tabla debemos seleccionar un proyecto de datos de todos los cargados en ejecución y una vez seleccionado el proyecto podremos elegir la tabla sobre la que vamos a configurar la seguridad.
De igual modo podemos configurar en la parte superior derecha los métodos aceptados para dicha tabla (GET, PUT, POST y DELETE).
Las tres pestañas de seguridad de campos procesos y búsquedas tiene la misma funcionalidad y usabilidad.
Por defecto la API REST no permitirá devolver información de un campo, proceso o búsqueda que tengan marcado el estilo privado.
En la de campos tenemos un check que nos permite indicar si queremos que todos los campos de la tabla que no sean privados estén disponibles para el API. Conviene marcarlos si queremos que estén accesibles la mayoría de campos, en ese caso los campos que seleccionemos en la rejilla inferior serán excluidos del retorno de información que genere el API.
Los campos que devolverá el JSON al ejecutar el proceso son los que se marquen en la pestaña campos del API, que no hay que programar nada en el proceso.
Si queremos dejar accesible un número pequeño de campos es mejor no marcar el check y hacer la selección de los campos accesible. En definitiva lo que se trata es de seleccionar de la lista el menor número de elementos utilizando el check para dicho fin.
Los procesos y las búsquedas funcionan igual con un check que permite seleccionar todas excluyendo las seleccionadas o solo incluir las seleccionadas si no marcamos el check.
Instalar y configurar el componente vModApache
Para poder acceder al API REST se usa el componente vModApache que permite que el servidor web Apache pueda servir de forma automática la documentación swagger y el API REST de tu aplicación.
La instalación lleva mismos pasos que la instalación habitual de vModApache.
Es extremadamente importante que configures el Apache en HTTPS con un certificado. De esta forma evitas que la información http viaje en plano y sea accesible por terceros.
Configuración del servidor Apache
Añadir una directiva location o virtualhost para conectarse a la instancia de la aplicación en el fichero de configuración de Apache. Ejemplo:
Reinicir el Apache
Una vez aplicadas las configuraciones, reiniciamos el servidor Apache.
Probar el API desde Swagger
¿Qué es Swagger?
Swagger es estándar para definir interfaces de API REST que permite que tanto personas como máquinas puedan entender y comprender las capacidades de un servicio sin acceder al código fuente o una documentación específica. Actualmente swagger forma parte de la especificación OpenApi.
El API REST de Velneo genera dinámicamente un fichero de definición swagger del API disponible en tu aplicación.
Para acceder Swagger usa la siguiente url:
https://demoapi.velneo.com/swagger/
Verás que al cargar la página propone la url de acceso a la instancia web que tenemos de la demo de Velneo vERP (https://demoapi.velneo.com/verp-api/vERP_2_dat_dat/swagger) y nos pide que introduzcamos la APIKey. En el caso de la demo de vERP ésta es: api123
Así ya podrás comprobar cómo funciona.
Para poder ver una documentación vistosa de tu API, puedes introducir tu url de definición de Swagger en la URherramienta swagger ui.http://petstore.swagger.io/, en la casilla superior y pulsar explorar. Si quieres acceder desde una red privada puedes descargar la herramienta swagger ui a tu ordenador y generar la documentación de tu API en local https://github.com/swagger-api/swagger-ui
Desde swagger ui, no solamente puedes ver la documentación de la API, sino que podrás probar los distintos recursos y testear contra los datos reales de las aplicaciones.
Recuerda introducir el API key que has puesto en vERP en la página de Swagger UI para poder simular las mismas opciones que se puedan hacer con dichao API key.
Doble factor de validación
Tras mostrarse la interfaz de Swagger, es necesario conocer el nombre de la API y asignarla a la variable “api_name”. Una vez comprobada su validez, se mostrarán los recursos disponibles y será necesaria la validación del “api_key” para usarlos.
Información del API Rest configurable
Los texto que se muestran en la pantalla inicial del API Rest, son obtenidos de la pestaña “Comentarios” del proyecto.
Una vez validado con un api_name, la información será sustituida por la que exista en las observaciones de la tabla del API.
Información de las tablas configurable
La información adicional mostrada en las tablas, procesos y/o búsquedas es obtenida desde el campo “Comentarios” de cada tabla.
Métodos append, cross y delete para los filtros
El filtrado por defecto realiza un {cross} (cruce de registros). Por ejemplo, si filtramos por los artículos que contengan la palabra “cámara” y como segundo filtro le asignamos que la familia sea “A01”, nos devolverá las cámaras cuya familia sea A01.
https://midominio.velneo.net/verp-api/vERP_2_dat_dat/v2/art_m?fields=id,name,fam&index[words]=camara&index[fam]=A01&api_key=apideejemplo
También es posible añadair registros en filtrado, usando el método {add}. Para que en el mismo ejemplo sume los registros que contengan la palabra cámara a los que contengan la familia A01, sería:
https://midominio.velneo.net/verp-api/vERP_2_dat_dat/v2/art_m?fields=id,name,fam&index[words]=camara&index[fam{add}]=A01&api_key=apideejemplo
También es posible quitar registros en el filtrado, mediante el método {delete}. Para que en el mismo ejemplo quite los registros que contengan la familia A01 dejando solo los que contengan la palabra “cámara” y no sean de la familia A01.
https://midominio.velneo.net/verp-api/vERP_2_dat_dat/v2/art_m?fields=id,name,fam&index[words]=camara&index[fam{delete}]=A01&api_key=apideejemplo
Método filterQuery
Permite hacer un filtro sobre una búsqueda
Obtener el ID, NAME y DSC de todos los artículos de la división 1:
https://midominio.velneo.net/verp-api/vERP_2_dat_dat/v2/art_m?fields=id,name,dsc&api_key=api123&filterQuery[emp_div]=1
Agrupamiento de recursos por tags
Todos los recursos mostrados por el API Rest (tablas con sus métodos, procesos y búsquedas) son agrupado por nombre de tabla y pueden mostrarse y/o ocultarse.
Interfaz
La interfaz permite añadir mediante botones más usables los parámetros de búsqueda, nuevos botones para copiar la llamada y la respuesta del API, …
Ejemplos:
Url Swagger vERP Demo: (clave api= api123)
https://demoapi.velneo.com/swagger/
Url Swagger para el registro de tu propia documentación:
http://petstore.swagger.io/
Todos los artículos:
https://demoapi.velneo.com/verp-api/vERP_2_dat_dat/v2/art_m?api_key=api123
Todos los artículos pero mostrando los campos id, name, dsc:
https://demoapi.velneo.com/verp-api/vERP_2_dat_dat/v2/art_m?fields=id%2Cname%2Cdsc&api_key=api123
Todos los artículos pero mostrando los campos id, name mediante un proceso:
https://demoapi.velneo.com/verp-api/vERP_2_dat_dat/v1/_process/art_m_bus?fields=id,name&api_key=api123
El artículo con id=1
https://demoapi.velneo.com/verp-api/vERP_2_dat_dat/v2/art_m?index%5Bid%5D=1&api_key=api123
Los artículos con id 1, 3 y 5
https://demoapi.velneo.com/verp-api/vERP_2_dat_dat/v2/art_m?index%5Bid%5D=1%2C%203%2C%205&api_key=api123
Todos los clientes:
https://demoapi.velneo.com/verp-api/vERP_2_dat_dat/v2/ent_m?api_key=api123
Si bien Swagger requiere CORS ((Cross-Origin-Resource-Sharing) si usamos el API Rest de Velneo vERP no es necesario activarlo en Apache, pues las propias cabeceras de nuestra API Rest ya lo activan directamente.
Última actualización
