Llamadas http y proxies

Hefesto dispone de tres directivas para realizar conexiones HTTP: Http (proxy), Pull (lectura con validación) y Push (escritura) .

Directiva Http (proxy)

La directiva Http envía la request actual tal cual a otro host y devuelve la respuesta. Es la forma más directa de crear un proxy. El message recibido se reenvía al host destino, y la respuesta del destino se convierte en la respuesta de la API.

post /user:
  CheckKey:
    directive: CheckKey
    expected: $.map.main.viewKey
    current: $.message.queryParam.api-key
  ModifyMessage:
    directive: ModifyMessage
    path: /ms/user
  Connection:
    directive: Http
    host: $.map.urls.usermshost
    timeout: 10
    connectTimeout: 3

En el ejemplo anterior, se valida un apiKey, se modifica el path (de /user a /ms/user) y mediante la directiva Http se redirige la petición a un microservicio externo.

Opciones de Http:

• host (obligatorio): dominio al que hacer la petición.
• timeout (opcional, default 10): segundos de espera tras establecer conexión.
• connectTimeout (opcional, default 10): segundos máximos para establecer la conexión.

Ejemplo de proxy total con all /requests:

all /requests:
  Http:
    directive: Http
    host: $.map.main.urlExternal

Directiva Pull (lectura con validación)

La directiva Pull realiza una petición GET (o POST si se usa body), valida la respuesta contra un JSON Schema y almacena el resultado en memory.

get /user:
  CheckKey:
    directive: CheckKey
    expected: $.map.main.viewKey
    current: $.message.queryParam.api-key
  ReadUser:
    directive: Pull
    host: https://mymicroservice.com
    path: /ms/user
    target: user

Pull busca automáticamente el JSON Schema en Maps/user.json para validar la respuesta. Si la validación falla, lanza excepción.

Opciones de Pull:

• host: obligatorio, dominio al que hacer la petición.
• path: obligatorio, path al que hacer la petición.
• target: clave en memory donde se almacenará la respuesta validada. También determina el JSON Schema a usar (Maps/{target}.json).
• body: opcional, array o string con el body. Sin body usa GET, con body usa POST.
• headers, queryParams: opcionales, arrays.
• cache: opcional, segundos de cacheo en Redis. Ejemplo: cache: 31536000 (1 año) para provincias.
• verify: opcional (default true), verifica status 2xx y valida JSON Schema.
• verifyStatus: opcional (default false), solo verifica status sin validar esquema.
• serverSideError: opcional (default false). true → lanza error 502, false → lanza 400.
• timeout, connectTimeout: opcionales (default 10).

Ejemplo de Pull con cache, queryParams y llamada local:

get /:
  GetProvinces:
    directive: Pull
    host: $.memory.hefesto-localhost
    path: /geo-bike-routes/provinces
    queryParams:
      validated: 'true'
    target: provinces
    cache: 31536000
  GetCountRoutes:
    directive: Pull
    host: $.memory.hefesto-localhost
    path: /geo-bike-routes/routeCount
    target: routeCount
    cache: 31536000

En este caso se hacen dos Pull en el mismo endpoint, ambos cacheados por un año (31536000 segundos). El primero obtiene las provincias validadas y el segundo el conteo de rutas. Ambos llaman a otra API local usando hefesto-localhost.

Ejemplo de Pull con POST (body incluido):

post /api/search:
  LoadSearch:
    directive: LoadAndValidateModel
    source: $.message.bodyAsArray
    target: search
  Pull:
    directive: Pull
    host: $.memory.hefesto-localhost
    path: /geo-bike-routes/search
    body: $.memory.search
    target: searchResponse

Directiva Push (escritura)

La directiva Push es similar a Pull, pero orientada a escrituras. No valida la respuesta contra un JSON Schema. Por defecto usa POST; si se usa el parámetro id, usa PUT.

post /user:
  CreateUser:
    directive: Push
    host: https://mymicroservice.com
    path: /users
    body: $.memory.user
    verify: true

Opciones de Push:

• host: obligatorio.
• path: opcional, si no existe se usa el del message.
• verb: opcional, por defecto POST (o PUT si se usa id).
• id: opcional, se concatena al path como /path/{id}.
• body, headers, queryParams: opcionales.
• verify: opcional (default true), verifica que la respuesta sea 2xx.
• timeout, connectTimeout: opcionales (default 10).

Ejemplo de Push con DELETE:

post /route/{routeId}/reset:
  Connect:
    directive: DatabaseConnect
  FindRouteById:
    directive: FindRouteById
    routeId: $.message.pathParam.routeId
  DeleteRoutePath:
    directive: Concat
    element1: /geo-bike-routes/route/
    element2: $.message.pathParam.routeId
    target: deleteRoutePath
  DeleteRoute:
    directive: Push
    verb: delete
    host: $.memory.hefesto-localhost
    path: $.memory.deleteRoutePath

En este ejemplo se usa verb: delete para hacer un DELETE a otra API local.

Conexiones locales

Para conectarte a otra API desplegada en el mismo virtual-host, usa como host la clave en memory hefesto-localhost. Las llamadas locales están siempre permitidas, incluso a APIs privadas.

# Ejemplo de llamada local
GetMunicipalityRoutes:
  directive: Pull
  host: $.memory.hefesto-localhost
  path: /geo-bike-routes/route
  queryParams: $.memory.queryParamsRouteList
  target: routes

Las variables globales hefesto-localhost se compone automáticamente de hefesto-org + hefesto-env, por lo que siempre apunta al virtual-host correcto.