Estrategia de migración de API REST a GraphQL - configuración del enrutamiento ( Ruby on Rails )

En la entrada anterior, le presenté la parte de trabajo preparatorio de cara a la migración de una API REST a GraphQL.

Vimos cómo mejorar la legibilidad y la robustez de sus acciones en los controladores haciendo un refactor y mejorando la cobertura de pruebas.

Aquí veremos cómo configurar correctamente el enrutador de Ruby on Rails para poner disponibles las dos versiones de nuestra API con el fin de asegurar una continuidad del servicio para las aplicaciones que consumen nuestra API REST.

Nota previa

Esta etapa no es estrictamente necesaria, puede simplemente agregar el punto de entrada principal de GraphQL por defecto, a saber POST /graphql en el archivo routes.rb de Ruby on Rails.

Sin embargo, en el proyecto en el que trabajé parecía más pertinente mostrar una verdadera distinción entre las dos versiones de la API.

Explicación

Para filtrar y enrutar nuestras solicitudes, puede usar varios métodos.

Cada método puede ser válido para su caso de uso; sin embargo, el versionado por URL no es realmente ideal.

En efecto, introduce complejidad adicional en sus llamadas a la API que no siempre es bienvenida, al añadir un parámetro que en el fondo no tiene mucho que hacer junto a los recursos solicitados.

Dicho esto, le presento los distintos métodos para versionar su API :

• Por ejemplo, puede versionar su API por la ruta de su URL

https://my-api.com/v1/articles

https://my-api.com/v2/articles

• O bien por un parámetro GET

https://my-api.com/articles?version=1

https://my-api.com/articles?version=2

• Por una cabecera HTTP personalizada

X-API-VERSION=1

X-API-VERSION=2

• Y finalmente por la cabecera HTTP Accept

En el siguiente ejemplo y para el resto de la entrada, consideraremos que utilizaremos este último método.

Para ser válida, el valor de esta cabecera debe tener el formato de un tipo MIME.

ACCCEPT=application/vnd.le-nom-de-votre-organisation.vXXX

Puede usar el nombre que desee entre les ‘vnd' y la versión.

Puede reemplazar XXX por el valor de la versión de su API.

Ejemplo

## api/contraints/version.rb
module API
  module Constraints
    class Version
      attr_reader :version
      attr_reader :default

   def accept_header_vendor
      "application/vnd.le-nom-de-votre-organisation.v#{@version}"
    end
  
      def initialize(options)
        @version = options.fetch(:version)
        @default = options.fetch(:default, false)
      end

      def matches?(request)
        @default || request
          .headers
          .fetch(:accept, "")
          .include?(accept_header_vendor)
      end
    end
  end
end

## app/routes.rb
Rails.application.routes.draw do
  scope module: :api, as: "api" do
    scope module: :v1, as: "v1", constraints: API::Constraints::Version.new(version: 1, default: true) do
      get "/posts", to: "posts#index"
      ...
    end
    
    scope module: :v2, as: "v2", constraints: API::Constraints::Version.new(version: 2) do
      post "graphql", to: "graphql#execute"
    end
  end
end

El uso del parámetro default de la clase API::Constraints::Version permite enrutar automáticamente a la primera versión de su API si la cabecera accept no está presente.

Conclusión

También es posible utilizar una gema para abordar este problema, pero creo que no es necesario introducir una dependencia adicional para casos de uso cubiertos por los ejemplos proporcionados en esta entrada.

Finalmente, como se indicó más arriba, en el marco de la migración de REST a GraphQL, este paso sigue siendo opcional pero permite marcar claramente la evolución de su API.