Hi all. My org needs an easy way to interact with GCP, so I'm writing a version of Cognitect's aws-api for GCP. I really like how Cognitect's library merges request parameters from all locations (headers, path, query string, and body) into a single "request map". Makes it nice and easy to interact with, not caring about where a particular parameter gets placed in the request. For my first cut I am working with the GCP Compute API. For that API, there are 50 API actions that have a parameter named the same thing in two different locations. This is problematic when creating a merged request map.
For example regionDisks.insert
accepts the parameter region
in the path and in the body. From the docs I can see the docs for the region
param located in the body that region
is "Output Only". This, presumably, means that the user would only ever specify region
in the path and never the body. Unfortunately there's no structural info to infer this from the OpenAPI spec.
Out of the 50 API actions, 47 have conflicting names between the path & the body. 3 of them have conflicting names in the query string & body. The path & body conflict seem to all be the case where the body parameter is "output only". The query string & body conflicts are less obvious to me. For example, regionDisks.insert
takes sourceImage
in the query & body. The doc for the parameter are somewhat similar but I'm not entirely sure if they are supposed to represent the same thing.
I'm looking for suggestions on how to handle this conflict. I see a few options.
1. Don't merge all parameters into a single, "simple" request map. Keep body, path, and query params separate.
2. Assign a priority to which named parameter "wins". i.e. path param then query param, then body param.
3. Create manual overrides for each API action that has conflicting names which ensures that all param names are unique (i.e., it either removes one in the case it is not necessary or renames one to something unique)
4. A combination of 2 & 3. Where 3 would apply only in cases where 2 doesn't work (currently don't have any of those)