Instalación y configuración

Configuración de endpoints

Un extremo (endpoint) es cada operación que la API expone. Se dan de alta desde la pantalla de Configuración de la API (Sit.a3ERP.Api.Config). Hay tres tipos, y de su tipo depende cómo se resuelve la petición.

Tipo	Método	Ruta	Resuelve
Vista SQL	GET	`/api/view/{nombre}`	Una vista de SQL Server (solo lectura)
Procedimiento almacenado	GET / POST	`/api/proc/{nombre}`	Un procedimiento almacenado, con parámetros
Operación personalizada	POST	`/api/custom/{dispatcher}/{nombre}`	Lógica a medida que ejecuta un worker

Antes de empezar

Necesitas la base de datos de la API ya creada (ver Instalación y puesta en marcha).

Endpoints SQL: la convención#

Cada entidad que se expone se apoya en dos objetos SQL con nombres normalizados. Mantener el prefijo SIT_API_ los hace fáciles de localizar:

Dónde se crean

Si la base de datos expuesta es una empresa de a3ERP, las vistas y procedimientos deben estar en el diccionario de extensibilidad de a3ERP, no creados sueltos en SQL Server (de lo contrario se perderían al regenerar o actualizar la base de datos). La API estándar para a3ERP entrega su propio diccionario justamente así (ver Puesta en marcha). En una base de datos SQL que no sea de a3ERP, se crean directamente en SQL Server (por ejemplo, con SQL Server Management Studio).

Una vista SIT_API_<ENTIDAD> — define qué campos se exponen.
Un procedimiento SIT_API_<ENTIDAD>_Parametrized — añade el filtro por identificador; si el parámetro llega NULL, devuelve todo.

Ejemplo para clientes:

CREATE VIEW [dbo].[SIT_API_CLIENTES]
AS
SELECT CODCLI, NOMCLI, NIFCLI, DIRCLI, TIPIVA, TARIFA, E_MAIL, FORPAG
FROM clientes WITH(NOLOCK)
GO

CREATE PROCEDURE [dbo].[SIT_API_CLIENTES_Parametrized] @CODCLI varchar(8)
AS
IF @CODCLI IS NULL
    SELECT * FROM SIT_API_CLIENTES
ELSE
    SELECT * FROM SIT_API_CLIENTES WHERE CODCLI = @CODCLI
GO

La vista es la fuente de la verdad sobre los campos; el procedimiento se limita a filtrar sobre ella.

Dar de alta el extremo#

En la pantalla de Configuración de la API, sección Extremos. Como en los usuarios, no hay un botón de «añadir»: se escribe en la fila vacía del final de la parrilla.

Pantalla de gestión de extremos en la configuración de la API

Por cada extremo defines:

Extremo — el nombre público que irá en la URL (/api/view/{nombre} o /api/proc/{nombre}). Puede diferir del nombre del objeto SQL.
Tipo — Vista SQL, Procedimiento almacenado u Operación personalizada.
Elemento — el nombre real del objeto de SQL Server que se ejecuta (la vista o el procedimiento); en operaciones personalizadas, el método del worker.
Dispatcher — solo en operaciones personalizadas (ver Workers y dispatchers).
Método HTTP y Descripción.

Extremo vs Elemento

El nombre del extremo (lo que se ve en la URL) y el objeto SQL que ejecuta son independientes. Puedes exponer Clientes y que por debajo ejecute la vista SIT_API_CLIENTES.

Parámetros de los procedimientos#

Los parámetros de un procedimiento se configuran al conceder el permiso a cada usuario (ver Usuarios y permisos), no al dar de alta el extremo. Al pulsar Permitir sobre un extremo de tipo procedimiento, se abre la ventana Configurar extremo, que lee automáticamente los parámetros del procedimiento desde SQL (nombre, orden y tipo):

Ventana «Configurar extremo» con los parámetros de un procedimiento

Sobre cada parámetro defines:

Nombre — ya viene del procedimiento; la API le antepone el @ al llamar.
Tipo — el tipo SQL del parámetro (también detectado).
Obligatorio — si la petición debe enviarlo.
Forzar valor / Valor — marca Forzar valor y escribe el Valor para fijarlo desde el servidor, ignorando el que mande el cliente.

El valor forzado es por usuario

Como los parámetros viven en el permiso, dos usuarios pueden tener el mismo procedimiento con valores forzados distintos. Es la vía para acotar a un usuario (por ejemplo, fijar una empresa o un filtro concreto).

Cómo se envían en la llamada (más detalle en Consumo de la API): en GET, como objeto JSON en base64 (texto empaquetado para que viaje en una cabecera) dentro de la cabecera Parameters; en POST, como objeto JSON en el cuerpo.

Operaciones personalizadas (custom)#

Para un extremo custom, el extremo solo declara el dispatcher y el nombre del método (tipo Operación personalizada). La lógica no está en la API: la ejecuta un worker de forma asíncrona, y la respuesta se recupera consultando la tarea. El detalle está en Workers y dispatchers.

Último paso: dar permiso#

Dar de alta un extremo no lo hace accesible. Hay que conceder el permiso correspondiente a los usuarios que deban usarlo; sin permiso, la API responde 403. Ver Usuarios y permisos.