Context

Meta has introduced Instagram Login, a separate authn mechanism that doesn't require Facebook Page to be linked to the Instagram professional account. The token obtained through it allows to access a subset of the IG API, but requires to use a different graph server: graph.instagram.com. In our app we need to call both the graph.facebook.com and the graph.instagram.com.

Problem

Koala’s configuration for the graph server is global. That makes it hard to use Koala for both servers in the same Ruby process.

I've considered a couple of workarounds, but none of them is solid:

• Swapping graph_server between requests → prone to race conditions under concurrency and hard to reason about.
• Using host_path_matcher / beta_replace with beta: true (example below) → kinda works when you don't need the beta feature, but relies on non-obvious semantics and remains brittle.

  Koala.configure do |config|
    config.host_path_matcher = 'graph.facebook.com'
    config.beta_replace = 'graph.instagram.com'
  end
  
  Koala::Facebook::API.new(ig_token).get_object("/me", {}, beta: true)

Possible Solutions

A few came into mind:

1. Introduce instance-local configs. Koala::Facebook::API.new could take a new argument (:config), with the default value of Koala.config. This would be a flexible solution which probably wouldn't require a major version bump. But maybe it is also not the most user-friendly one in terms of the UX, especially when it gets to that new graph server.

   # In initializer:
   
   Koala.configure do |config|
     # ...
   end
   
   KOALA_IG_CONFIG = Koala.config.dup.tap do |config|
     config.graph_server = "graph.instagram.com"
     # ...
   end
   
   # In app code:
   
   fb_graph = Koala::Facebook::API.new(token) # `:config` defaults to `Koala.config`
   ig_graph = Koala::Facebook::API.new(token, config: KOALA_IG_CONFIG)

2. Introduce Koala::Instagram namespace. The idea here is to back each graph server with it's own namespace and allow to have separate configs for each. Probably it'll require more work than others, and I'm not sure if the pattern introduced here is a good one. Besides, there would definitely be some confusion when users will need to access IG API using FB token, as the natural thing will be to try Koala::Instagram::API

   # In initializer:
   
   # Uses Koala.config by default to preserve backwards compatibility
   Koala::Facebook.configure do |config|
     # ...
   end
   
   Koala::Instagram.configure do |config|
     # ...
   end
   
   # In app code:
   
   fb_graph = Koala::Facebook::API.new(token)
   ig_graph = Koala::Instagram::API.new(token)

3. Add a new setting for IG graph server and a new argument to Koala::Facebook::API.new, something like graph_server :instagram/:facebook, with :facebook as a default one. This one also has some issues: it is not as flexible as instance-level configs, and I'm not sure how well it'll work with other features. Besides, even if currently the two graph servers work in the same way and have the same versioning, it doesn't mean that it'll always be like this. Switching just the graph_server might not be enough in the future

   # In initializer:
   
   Koala.configure do |config|
     config.graph_server = "graph.facebook.com" # deprecated
     # Defaults to {facebook: config.graph_server, instagram: "graph.instagram.com", ...}
     config.graph_servers = {
       facebook: "graph.facebook.com",
       instagram: "graph.instagram.com"
     }
   end
   
   # In app code:
   
   fb_graph = Koala::Facebook::API.new(token) # or with `graph_server: :facebook`
   ig_graph = Koala::Facebook::API.new(token, graph_server: :instagram)

Would love to hear your thoughts