search

tweag / nixpkgs-graph-explorer

Explore the nixpkgs dependency graph
MIT License
16 stars 0 forks source link

Deprecate `/gremlin` API endpoint in favor of a dedicated `/graph` endpoint #128

Open dorranh opened 1 year ago

dorranh commented 1 year ago

The original functional spec for this application included the ability for users to submit ad-hoc queries via the Gremlin query language. Following user feedback which indicated that this query language was not easy to use and not particularly useful for core use-cases, UI support for such queries has been dropped in #121. However, we continue to use the same API endpoint which was designed for this feature to power the graph visualization in the UI, having the web client generate Gremlin query strings and submit them to the API for evaluation.

This approach introduces a lot of unnecessary baggage such as requiring the web client to be "Gremlin-aware" as well as exposing a public endpoint which we do not intend to support moving forward. Additionally, it is quite error prone when used for populating the graph visualization since it involves a lot of unnecessary wrangling. For example, the evaluation looks something like:

flowchart TD
    id1([1. Browser issues Gremlin query to /gremlin endpoint])
    id2([2. API validates query, submits to Gremlin Server])
    id3([3. Gremlin Server further validates query, permissions, etc.])
    id4([4. Gremlin Server evaluates query and returns results])
    id5([5. API parses results, attempting to detect whether a renderable result was generated and returning a CytoscapeJS-compatible object if possible])
   id6([6. Client parses the API response, rendering CytoscapeJS data if is available])
   id1 --> id2
   id2 --> id3
   id3 --> id4
   id4 --> id5
   id5 --> id6

I would propose that we add a dedicated /graph endpoint which always returns a response which can be used for populating the graph visualization. This will help reduce the wrangling happening in the above logic and should also allow us to provide a more reliable implementation for fetching dependency graphs. It will also allow us to perform optimizations in the endpoint's implementation to help ensure the efficiency of the Gremlin traversals it generates.

GuillaumeDesforges commented 1 year ago

That's a very good point. Indeed it'll be much easier to work on the Gremlin queries on the api side with the proper types and libraries.