GraphQL API Querying for TPRM

Today we’ve released Fluvial’s new GraphQL query endpoint. This feature makes it easier to develop new, custom User Interface or API integration apps.

What is GraphQL?

GraphQL is a communication standard for fetching data. It’s delivered over HTTP which means it’s accessible by web browsers or application code. Graphql’s main feature is that the consumer (the client system) can specify whatever data they require from a deep, hierarchical structure. Such an interface can replace many individual REST API endpoints, each of which would return a different data. Effectively, GraphQL moves work from the client developer onto the server - the developer specifies the data and the server must deliver it.

How does Fluvial use GraphQL?

Fluvial TPRM Projects are based around a questionnaire. There’s an obvious hierarchical structure to the data in a Project, and permissions are mostly scoped to the Project ID, so it’s a great fit for a GraphQL query.

Implementation & Performance

Fluvial’s core application is a Python web application. Python is a wonderful language with an extraordinarily rich infrastructure of tools and libraries. It’s also very concise yet readable - which pays off in faster development and easier maintenance. The downside is that Python is slow - that’s a necessary tradeoff for the concision and readability. The good news is that, most of the time, that slowness doesn’t matter at all. Most of the work in handling an http request (think clicking a browser link) is in handling the http envelope, fetching database data, and then transforming DB data into JSON. Fluvial implements all these steps in Python extension modules written in C or Rust - fast, compiled languages.

GraphQL changes this calculation a little. By moving more working onto the server, GraphQL queries demand more server processing time. The GraphQL query must be parsed followed by highly dynamic SQL query building. Since Fluvial has a 20:1 read-to-write ratio, optimizing read performance with Go allows us to handle significantly more traffic per server, reducing infrastructure costs.

With this in mind, we decided to implement the GraphQL query endpoint as a Go language webservice. We use the excellent schema-first gqlgen package by 99Designs to generate the GraphQL scaffolding and Squirrel to help manage the necessarily dynamic SQL queries. Authentication and Authorisation are still performed in the Python application, but GET requests for Project data are now delegated to the Go GraphQL server, which performs a second level of authorisation.

Results so far are encouraging. Response time for a simple object lookup query is around 3 milliseconds. For a deeply nested, worst case query with hundreds of properties, this goes up to around 10 milliseconds.

Query Format

Here’s an example of a query which fetches Project, Section and Questions in one shot:

query {
  project(id: 123) {
    title
    sections {
      title
      questions {
        title
        tags {
          name
        }
      }
    }
  }
}

Benefits for TPRM UI Developers

GraphQL transforms the developer experience by replacing multiple REST calls with a single, precisely-tailored query. Fetch a project, its sections, questions, and tags in one request—getting exactly the fields you need, nothing more. This eliminates over-fetching, reduces bandwidth and removes the need to coordinate multiple API endpoints. The self-documenting schema through GraphQL Playground means less time reading docs and more time building features. TPRM developers can iterate faster, experiment freely, and deliver responsive UIs without wrestling with data plumbing.