[GIG][API] Design an API for Data Querying

[vibhatha]

Description

Introducing a more flexible and powerful API for application developers to use the GIG more efficiently. There are limitations when it comes to complex queries which require multiple calls to gather the information and also compute aggregation operations to obtain the required response. This is a cumbersome process which needs to be streamlined. In terms of one or two applications using REST API would work as the requirements could be narrowed down to a greater context since there is knowledge about each application. But when extending this application development for third-party users, the API developers should be able to provide a more flexible and efficient API.

Goals

1. Develop an initial version of an API catering to flexible application development.
2. Using REST APIs where it is necessary though do the necessary migration for complex queries
3. Using GraphQL API in OrgChart

Non Goals

1. Replacing every REST API call with GraphQL (doesn't imply 100% conversion later, though choose what is suitable).
2. Writing a new specification for GIG which can abstract away a layer on top of GraphQL API.

Motivation

GIG allows users to query information via a REST API. However, this has limitations when it comes to executing complex queries, which would either be over/under fetching. In developing various applications, we may have to rely on more complex queries than we see in the OrgChart App. Such queries are hard to represent using a REST API [1]. A better approach must be implemented to provide better performance and improve usability so that third-party developers can develop applications quite effectively.

As a solution, turning into the GraphQL API usage provides far more flexibility in terms of executing complex queries. This requires adding a server to resolve complex queries as that is one of the most fundamental parts of using GraphQL when consuming multiple data sources like various databases and third-party resources [2].

Sub Tasks

• [GIG][API] GraphQL Literature Review #25
• [GIG][API] Document GraphQL and REST API usage in a balanced way #26
• [GIG][API] GraphQL PoC for OrgChart App #27
• [GIG][API] Develop a GraphQL API for Generic Usage #28
• [GIG][API] Use Developed GraphQL API for OrgChart #29

Success Metrics

1. Ability to run OrgChart queries quite efficiently.
2. Ability to provide a generic API which can execute queries which have not been already attempted.

Testing

TBD

Assumptions

1. Complex queries require a generic API endpoint.
2. Unexplored novel applications could contain far more complex queries than what is expected in the current applications.

References

1. https://aws.amazon.com/compare/the-difference-between-graphql-and-rest/
2. https://www.howtographql.com/basics/3-big-picture/