GraphQL API

[AdamMcAdamson]

As this initial API's intention is to serve not only initially serve Project Nebula initiatives, but also general users of our API, I am increasingly leaning towards implementing a GraphQL API instead of our current REST API. Given the unknown use cases for our users, the interconnected nature of our dataset, and the subsequent impossible task to prevent over and under fetching of data, this appears to be a great opportunity to improve the API.

This would ease the workload for our projects who want to perform operations over specific parts of our dataset (i.e. UTD Trends using grade data), ease development for general users of our API (the Graph_i_QL explorer is super powerful), and ease the workload on our end in terms of eliminating all future endpoint development, and will assist us in outlining strongly typed models for our API data that we are confident in.

If we were to go down this route, for our projects, the current state of the Golang refactor can provide the foundation for them to develop off of. For our GraphQL API we have two options: we could develop the GraphQL endpoint in our existing server, or we could create a new server, and use a tool like https://gqlgen.com/. After it is live, we can sunset and remove the existing REST API (endpoints) as we see fit.

Please let me know what you think.

[AdamMcAdamson]

I have created a separate API in the graphql tree of my fork using gqlgen. I have created the initial GraphQL SDL schemas and generated models from it. There are a few changes to our schemas that we'll probably want to implement, all of which have been commented in the respective graph/schema/*.graphqls files.

The generated models also give us insight into how we should be going about creating types for marshalling and unmarshalling with go.
They basically create an interface which has a function that is shared between the different types.

type Requirement interface {
	IsRequirement()
}

type ChoiceRequirement struct {
	Choices *CollectionRequirement `json:"choices"`
}

func (ChoiceRequirement) IsRequirement() {}

type CollectionRequirement struct {
	Name     string        `json:"name"`
	Required int           `json:"required"`
	Options  []Requirement `json:"options"`
}

func (CollectionRequirement) IsRequirement() {}

// ...

There are some liberties I took as a result of some nuances about GraphQL, which I believe are all documented in comments.
Mainly:

1. GraphQL removes the need for the type fields (they are still useful (and required(?)) in our DB).
2. GraphQL doesn't support static values in schema (we would however use static types in create and update calls in our resolvers).
3. Because of 1 and 2 - there are no shared fields for requirements (and exams), so we are using a Union type.
4. The enum convention in GraphQL is for values to be all caps. So we need to update our DB, or handle this in our resolvers.

So far GraphQL seems like an all-around win to me. I'd love to have everyone's comments on this so far.

I'm leaning towards having the GraphQL API be separate as gqlgen automates a ton of work removes the need for Gin and gqlgen automates a ton of work (though we can combine our APIs while using still gqlgen, and we may want to leverage it regardless).

From here we'd be looking implement a few query types and resolvers as a POC.

Please let me know your thoughts.