Endpoints

Para declarar endpoints en cualquier API de Hefesto sólo tienes que añadirlos al api.yaml, en la sección de endpoints:

  endpoints:
    get /user/{id}:
      Ping:
        directive: Ping
    post /user:
      Ping:
        directive: Ping

En el caso anterior hemos declarado dos endpoints, un GET a /user/{id} y un POST /user. Los dos endpoints ejecutan una sola directiva Ping, que devuelve al cliente que haga la request un 200 con un JSON que incluye el mensaje "pong".

Una vez desplegada la API, podrás hacer peticiones contra estos endpoints tal como se explica aquí.

Podrás acceder al id del GET /user/{id}, desde una directiva customizada a través del state, o desde el api.yaml, a través de un alias.

Habrá casos, en que quieras que todas las peticiones que entren en la API, tengan el mismo comportamiento, esto lo puedes hacer así:

  endpoints:
    all /requests:
      Ping:
        directive: Ping

De esta manera todas las peticiones, tengan el verbo y el path que tengan, serán manejadas por el endpoint especial "all /requests". Puedes usar esta caracterítica con múltipes propósitos, un par de ejemplos:

• Tu API puede hacer de middleware contra un microservicio y delegar en la capa de Hefesto la seguridad, logs, o lo que quieras.
• En una API con endpoints que sirven vistas, puedes combinar "all /requests" junto con el resto de endpoints, para que si una petición no puede ser resuelta por ninguno de ellos, "all /requests", devuelva una vista con un 404, tal como se muestra en el ejemplo inferior.

      endpoints:
        get /home:
          View:
            directive: View
            name: home
        get /about:
          View:
            directive: View
            name: about
        all /requests:
          View:
            directive: View
            name: not-found-view

Flow de las directivas

Las APIs, tienen un api.yaml, donde se definen sus endpoints. Al hacerse una llamada a un endpoint, se ejecutan todas sus directivas, siguiendo un flujo, que tiene las siguientes reglas:

• Primero se ejecutan las directivas en before.
• Luego se ejecutan las directivas del endpoint.
• Por último, se ejecutan las directivas en after.
• Las directivas siempre se ejecutan en orden, una detrás de otra.
• Si una directiva tiene el group ERROR_FLOW, la directiva sólo se ejecutará cuando una directiva anterior lance una excepción.
• Si una directiva tiene el group AFTER_FLOW, se ejecutará siempre, haya o no haya errores.
• Si una directiva no tiene ningún group, solo se ejecutará si NO se ha lanzado una excepción previamente..
• Puedes crear groups personalizados, diferentes de ERROR_FLOW y AFTER_FLOW, y activarlos/desactivarlos cuando te convenga, para dar al flujo lógicas más complejas.

Por ejemplo en:

  key: poems
  before:
    CheckKey:
      directive: CheckKey
      expected: $.map.main.key
      current: $.message.header.api-key
  after: 
    OnError:
      directive: OnError
      groups:
        - ERROR_FLOW
    Log:
      directive: Log
      groups:
        - AFTER_FLOW
  endpoints:
    get /user/{id}:
      Connect:
        directive: DatabaseConnect
      ReadUser:
        directive: ReadUser
        id: $.message.pathParams.id
      Prepare-Response:
        directive: ModifyMessage
        status: 200
        headers: 
          Content-Type: application/json
        body: $.memory.model-user
    post /user:
      LoadUser:
        directive: LoadAndValidateModel
        source: $.message.bodyAsArray
        target: user
      Connect:
        directive: DatabaseConnect
      SaveUser:
        directive: SaveUser
        user: $.memory.model-user
      IdResponse:
        directive: IdResponse
        id: $.memory.idUser

En una llamada contra post /user, donde no ocurra ningún error, el flujo de diretivas será:

• CheckKey: porque está dentro de before.
• LoadUser: porque es la primera directiva del endpoint.
• Connect: porque es la segunda directiva del endpoint.
• SaveUser: porque es la tercera directiva del endpoint.
• IdResponse: porque es la cuarta directiva del endpoint.
• OnError: no se ejecutará, está dentro de after, y se ejecutaría, de no ser porque está en el group: ERROR_FLOW. Las directivas en este group solo se activan cuando se lance una excepción.
• Log: porque es la siguiente directiva de after, después de OnError. Además gracias al group: AFTER_FLOW, la directiva se ejecutará después de que la respuesta haya llegado al cliente, permitiendo Hefesto que cualquier tarea no necesaria para el cliente, pueda ser ejecutada después de recibida la respuesta, consiguiéndose así mejoras en latencia.

Si se produjera un error, en Connect, porque la base de datos estuviese caida, se lanzaría una excepción, lo que provocaría que ninguna de las directivas siguientes se ejecutaran, excepto las que estén en los group: ERROR_FLOW y/o AFTER_FLOW. Ver el tratamiento de errores al respecto.

Ir a la home