Optional GraphQL interface

[bobmcwhirter]

Some parties will enjoy/prefer a GraphQL-oriented API for accessing information within Trustify.

Not as our own primarily internally-consumed API, but for unknown integrations external to us.

Seaography? Postgres GraphQL extension? Dunno!

[gildub]

A GraphQL API solution would be redundant with a REST API.
Having a GraphQL API would therefore allow to save on development efforts.

The contenders:

• Seaography
• Juniper
• async-graphql

Seaography

• Pros:

  • Integration with SeaORM

• Cons:

  • Mutations not available yet
  • Seems not very actively maintained

Juniper

• Pros:

  • Actively maintained

• Cons:

  • Actix-web not maintained by Juniper

async-graphql

• Pros:

  • Was built with Async/Await in perspective
  • Supports middleware
  • Supports redacting sensitive inputs (logs without worrying about leaking this stuff)
  • Actively maintained

• Cons:

  • I haven't find any yet

From above, async-graphql seems to be the better candidate for us.

[bobmcwhirter]

Let's only worry about the read side of this problem to start.

If seaography has "good" integration with our usage of SeaORM, that might be worth exploring. I believe it uses async-graphql underneath.

[gildub]

Well I'm worried about having GraphQL and not using it for serving API endpoints where it helps.

I believe this is a strategic decision to be taken because REST and GraphQL features overlap each others to serve an API.
Let me explain why.

Depending on the type of a project, one or the other could be used.
From simple or very specialized API, REST is perfectly fit for the task where GraphQL schema overhead would be overkill.
For an application requiring a complex API, GraphQL makes more sense because it brings powerful features, the first one being efficiency to retrieve entire set of data with a single network request, and API aggregation would be another benefit.

Of course since the Trustify project is micro services then we could use REST for some services and GraphQL for other services.
My concern here remains for the more complex APIs we ought to implement with GraphQL as the the ideal targets for GraphQL meanwhile if we start serving the API with REST (out of habit ) then we end up not using GraphQL where we should or we either create tech debt.

The feedback from some devs on the trustification expressed a bad experience with GraphQL from GUAC.
I don't know why that happened.
Meanwhile I'm not trying to push GraphQL blindly.
I did a proof of concept for MTV (Konveyor) serving GraphQL from Golang (our back-end) for a JS/TS/React front-end.
That works perfectly fine and showed how we could benefit from GraphQL powerful features. (We never pushed that to production because we downsized MTV).

Of course with a new/recent tech we have to draw the line between stability, community support against technology jump that a new paradigm can bring. This is not the case here, GraphQL has been out long enough

Therefore to decide which tech to use for a project or its micro services parts boils down to evaluate the API needs and match its complexity against the more adapted tool.

Then if Seaography doesn't support mutations then it cannot be used to fulfill a proper API service.

[bobmcwhirter]

All valid points.

Let's see where we can get with your work; meanwhile, I think we power forward with at least the known-unknowns around REST until then.

[bobmcwhirter]

@gildub if you find success before next week's meeting, I'd vote for plonking a link to a video or whatever write-up/example/demo you have here. Relentless forward progress!

[gildub]

@bobmcwhirter,

Juniper ended up to be the most straightforward to implement and is pretty aligned with GraphQL standard.

The following branch contains a basic GraphQL API using Juniper with requests for SBOMs (get all sboms, get one sbom and create a sbom).
More objects and relationships will be next :

https://github.com/gildub/trustify/tree/graphql-poc

GraphQL API examples

Using CURL

Retrieving SBOMs

$ curl -s localhost:8080/graphql -H "Content-Type: application/json" -d '{ "query": "{sboms { id location sha256}}" }' | jq
{
  "data": {
    "sboms": [
      {
        "id": 1,
        "location": "file:///home/gildub/pro/rhtpa/SBOMs/test/batch1/736DA1C6A24D404.replicate1.cdx.json",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      }
    ]
  }
}

Create (Mutate) a SBOM

$ curl -s localhost:8080/graphql -H "Content-Type: application/json" \
-d '{ "query": "mutation CreateSbom($sbom: SbomInput!) { createSbom(sbom: $sbom) {location sha256}}",
"variables": { "sbom": { "location": "file:///home/gildub/pro/rhtpa/SBOMs/test/batch1/736DA1C6A24D405.cdx.json","sha256": "123456"}}}' | jq

{
  "data": {
    "createSbom": {
      "location": "file:///home/gildub/pro/rhtpa/SBOMs/test/batch1/736DA1C6A24D405.cdx.json",
      "sha256": "123456"
    }
  }
}

Using Graphiql

Screencast.from.2024-03-26.17-10-10.webm

[gildub]

The Juniper initial easiness was shadowed once we approached more advanced features such as exploiting one to many (1:m), or many to many (n:m) relationships. Juniper unfortunately requires to replicate the model's structure (because the object's structures must be in the same crate scope which doesn't work for us because the model is in another crate).

The next step is to investigate Async-graphql which I initially put aside because mutation are not available yet. And also because in practice Juniper was really easy to get started with.
Meanwhile since our initial needs for graphql require only read access, this is not a limitation.

[gildub]

@bobmcwhirter, from what we've learned and my above comment I'm working on a graphql POC using async-graphql.

[JimFuller-RedHat]

Random observation: graphql is fine for read ... though can often be challenging to support updates especially if there is no graph store backend.

[gildub]

@JimFuller-RedHat, thank you for providing feedback.

Could you please detail :

especially if there is no graph store backend

If there is a graphql endpoint then a schema is available included for mutations to work on such schema, independently from where it's stored. But maybe you meant something else.

[JimFuller-RedHat]

Ah right not trying to be cyptic ... I have found putting a graphql api interface over a non graph store can sometimes be a recipe for pain with writes/updates ... the problems start because graphql promises can be hard to duplicate in relational store ... read is mostly fine ... write (eg. using graphql with POST/PUT/DELETE) however can cause a 'drip drip' of fixes/enhancements. Don't let me put you off using graphql!

[gildub]

@JimFuller-RedHat, no worries, the more we're realistic about GraphQL pros/cons, the better.
Well, we're effectively not using a graph store as we're using Postgresql. Although GraphQL could be used on top of a REST API, in which case the resolvers will be using REST verbs. We're not using such approach, the resolvers is taping into ORM framework to retrieve data (and eventually for mutations too).
That said I understand a graph store could be more efficient and avoid to optimize the N+1 requests when using ORM .

[JimFuller-RedHat]

yes, handling multiple mutations in one REST invoke can lead to a lot of execution passes, sometimes sync, sometimes async - though what is more frustrating is sometimes the need to puzzle out correct order of mutations (and deal with any notions of distributed/atomic commit behaviour) often turns out to be more work then its worth ... then there is the sanity checking if a graphql mutation 'makes sense' in context eg. can lead to excessive work implementing guard rails so a user cannot do inane/stupid requests (which really is not their fault if graphql provides the syntax).

[gildub]

@JimFuller-RedHat, thank you for this insight !
Although we won't initially have such issues as we're going to use GraphQL for Read only requests.
Meanwhile, if going with mutations, and learning from your experience we'll definitely have to guard the user from complex changes.

[gildub]

Initial POC using async-graphql framework : https://github.com/gildub/trustify/tree/async-graphql-poc

[gildub]

The following PR is adding an /graphql endpoint to the existing web service along the REST API.

https://github.com/gildub/trustify/tree/server-grapqhl

This is replacing the former async-graphql-poc branch mentioned above.
If the POC is accepted it will be submitted as a PR to trustify/trustify.