MediQL

Developer Tool for GraphQL Response Visualization & Error Transparency

Description

MediQL is an innovative GraphQL developer tool that builds upon the capabilities of GraphiQL, an open-source web-based integrated development environment (IDE) for GraphQL. With MediQL, you can supercharge your GraphQL workflow by leveraging advanced features such as query response visualization, error indication, and real-time observation of API response statuses and objects. By seamlessly integrating with GraphiQL, MediQL enhances your development experience and empowers you to streamline debugging, optimize performance, and achieve greater efficiency in building GraphQL APIs.

Currently in Alpha.

Installation (part 1)

Fork this repo and clone to local machine.
Run npm i in both server directory and client directory to install respective dependencies.
Create a .env file in the server folder, and assign the global environment variable MONGODB_URI with your personal MongoDB connection string (personal database connection string).
Run npm start dev in the root directory.
(NOTE: Server will be running on localhost:3003 & Client will be running on localhost:8080)
Visit http://localhost:8080/.

You should be able to see GraphiQL's GUI loaded up, however, we will need to integrate and connect your personal GraphQL project with this application before being able to test your multi-layered queries!

Let's install the necessary dependencies into your personal GraphQL project as it will be needing this to create the integrated development environment (ide).

Installation in your personal GraphQL Project (part 2)

As MediQL is built on top of GraphiQL, it is necessary to have GraphiQL and a /graphql server route set up prior to installing MediQL.
Run npm i express-graphql to install dependency for GraphiQL (Visit https://github.com/graphql/graphiql for more information)
Run npm i mediql to install dependency for MediQL (Visit https://github.com/MediQL/mediql-npm-package or https://www.npmjs.com/package/mediql for more information)
Run npm i cors to install cors dependency as the CORS middleware enables Cross-Origin Resource Sharing, allowing your GraphQL project's server to handle requests from different origins, such as MediQL's application.

Now, let's move on to configuring your personal GraphQL project and integrate it with MediQL!

Usage

Ensure that your GraphQL project's server application will be able to respond to requests from different domains or ports, making it easier to handle cross-origin requests from MediQL.

const app = express();
const cors = require("cors");
app.use(cors());

Within your GraphQL project, in your schema file or file with resolvers (i.e., schema.js), import the postOriginResp function from the mediql package using CommonJS module syntax.

const { postOriginResp } = require("mediql");

In that same file, invoke the postOriginResp function inside each of your resolver functions with the specific arguments of response, parsedResponse, and info.

//declare & assign the response variable as the result of your fetch request to an external api url 
const response = await fetch('url');
//declare & assign the parsedResponse variable as the parsed JSON response of your response variable
const parsedResponse = await response.json();
//invoke mediql's packaged function with the arguments of response, parsedResponse, and info respectively.
postOriginResp(response, parsedResponse, info);
//return parsedResponse as this is the typical GraphQL resolver set up
return parsedResponse;

Before the next step, you will need to have a '/graphql' endpoint route configured for GraphiQL in your server file. (Visit https://github.com/graphql/graphiql for more information)
In your server file (i.e., server.js), import the postQueryResp function from the mediql package using CommonJS module syntax.

const { postQueryResp } = require("mediql");

Within your '/graphql' endpoint route, include the extensions option and specify the function outlined below and invoke the postQueryResp function with the argument of result inside of it.

app.use(
  "/graphql",
  graphqlHTTP({
    schema,
    graphiql: true,
    context: ({ req }) => ({ req }),
    extensions: async (
      { document, variables, operationName, result }) => {
      //invoke postQueryResp function with the argument of result.
      postQueryResp(result);
    },
  })
);

Make sure your GraphQL project's server/client are running on a PORT that is not localhost:3003 or localhost:8080 as the integrated development environment (IDE) will be using those ports.
Now, start up your GraphQL project server and head over to http://localhost:8080/ on your browser.
Input your GraphQL project's server PORT# and get those queries in!

Features

✨ GraphiQL ✨

GraphiQL's user interface & functionality is provided for testing GraphQL queries alongside our visualizer extension, making a completely integrated development environment for developers. Plug in your GraphQL project's server PORT and get querying!

✨ Query Response Visualization & Error Indication ✨

When a GraphQL query has been made, MediQL visualizes the query response with as a tree of nodes on the right side of your screen. Errors are indicated in red. Possible errors or null values are indicated in orange. Lastly, completed queries with no issues are indicated in green.

✨ API Response Transparency ✨

As we all know, GraphQL responses do not provide API Response Transparency. If a field is not available, the developer ends up with a null value, with no indication of what type of API error was given originally. The developer would be at risk of the ambiguity of errors.

This is where MediQL comes in and saves the day!

Each node in the visualizer is clickable and provides insight on that specific resolver's query response! The original API response's status codes and objects are provided to you with no additional call to the external API's. The developer has the ability to look into the original API's response object as well.

✨ Light/Dark Theme ✨

We also offer a light and dark theme that is integrated with GraphiQL's user interface which allows users to customize their experience and choose the visual style that best suits their preferences and needs.

Tech Stack

Read more about the importance of Error Transparency!!

Co-Creators

James Huang
- GitHub
- LinkedIn
Lily Hoong
- GitHub
- LinkedIn
Noah Tofte
- GitHub
- LinkedIn
Jake Ruiz
- GitHub
- LinkedIn

Acknowledgements

This project uses GraphiQL, an in-browser IDE for exploring GraphQL APIs. GraphiQL is a powerful tool for testing and debugging GraphQL queries, and it has been instrumental in the development of this project.

In addition, our team has developed an extension for GraphiQL that adds a response visualizer and error indicator, which enhances its functionality and makes it even more useful for developers. We would like to thank the creators of GraphiQL for providing a solid foundation for our extension, and for inspiring us to build upon its features.

We also want to thank our team for their hard work and dedication in developing the extension and making it available to the community. We hope that our extension will be helpful to other developers who are using GraphiQL to explore and test their GraphQL APIs.

Contributing

Thank you for your interest in contributing to our project! We welcome contributions from developers, designers, testers, and other contributors who share our passion for building great software.

Prerequisites

Before you start contributing, you should have knowledge of HTML, CSS, and JavaScript, as well as experience with Git and GitHub. Familiarity with React and GraphQL is also a plus.

Guidelines

To contribute to our project, please follow these guidelines:

Fork the repository and clone it to your local machine.
Create a new branch for your changes and make your changes.
Submit a pull request to our repository and describe your changes in detail.
Wait for a code review and address any feedback from our team.
Once your changes have been approved, we will merge your pull request into our repository.

If you need help getting started or have any questions, please reach out to us on our GitHub repository.

Code of conduct

We expect all contributors to follow our code of conduct, which is based on the Contributor Covenant (http://contributor-covenant.org). This code of conduct outlines our expectations for behavior and communication among contributors and helps to create a respectful and inclusive community for everyone.

Attribution

We would like to acknowledge and give credit to all contributors who have contributed to our project, including code, documentation, and other contributions. Thank you for helping us to make our project better for everyone!

Roadmap

Implement support for multiple GraphQL APIs.
Refactor the codebase to improve maintainability.
Deploy the application as a website so that developers can use it without cloning the repo.

oslabs-beta/MediQL