GraphQL is a powerful technology that is altering the API development landscape. Since its release into the public domain by Facebook in 2015, the specification has been implemented in a variety of programming frameworks including but not limited to Java, .NET, Python, Node.js and Ruby. The GraphQL Query Language (GQL) provides developers with the ability to use a GraphQL API in a declarative manner. (For a deeper dive on GraphQL fundamentals, see ProgrammableWeb's Guide to Understanding, Building, and Using GraphQL APIs). Unlike RESTful APIs which may require multiple trips to and from an API to get all the data you need, GraphQL enables you to get exactly the data you want with only one trip to the network. It's a significant difference.
While it's true that GraphQL makes using an API a more flexible undertaking, there is a price to be paid for the benefit: increased complexity. GraphQL is a system in which everything is essentially a type in a unified type system. This includes not only data structures but also the basic GraphQL operations; query, mutation, and subscriptions. In addition, GraphQL supports interface inheritance, type inheritance, custom scalars and more. What can start out as a simple "Hello World" API can evolve in complexity to an API that has tens maybe hundreds of types. Managing it all can be a challenge. This is where the benefit of third party GraphQL tools comes into play.
One such tool is GraphQL Editor. GraphQL Editor allows developers to create full-fledged APIs in GraphQL using the visual development paradigm found in tools such as Visual Studio with its Class Diagram feature and Eclipse using one of the many Unified Modeling Language(UML) plugins available. Among GraphQL Editor's more interesting features is its ability to create a block diagram all of your GraphQL entities (similar to how Microsoft's Visio was often used as a layout tool to block diagram the modules of a software project). This ability alone could make GraphQL Editor a nice arrow to have in your GraphQL quiver of tools. However, as we'll enumerate later in this review, that feature has some shortcomings that, for many, will diminish the overall value of the tool until it is fixed.
Applying the notion of visual programming to GraphQL development is an intriguing idea that makes GraphQL Editor worth reviewing. We'll take a look at its backstory and how the tool works. We'll discuss both its benefits and its challenges. And then we'll wrap up with a general assessment.
Let's start with how GraphQL Editor came to be.
GraphQL Editor, the Company
GraphQL Editor Ltd is headed by Artur Czemiel (CEO), Kamil Matysiewicz (CTO), Robert Matyszewski (Head of Growth), and Tomasz Poniatowicz (CMO). The company is based in Bialystok, Poland which is about 120 miles northeast of Warsaw. According to Matyszewski, the principals started GraphQL Editor for two reasons. First, they wanted to have a more direct influence on the shaping of products, which they found difficult to have when working in a larger corporate structure. Second, they wanted the freedom to pursue their mission to improve software development for the GraphQL community by providing state-of-the-art products that do both visual editing and automated code generation.
The result of their efforts is GraphQL Editor which was released by the company of the same name as an open-source project on September of 2018.
The essential value proposition of GraphQL is that it's a browser-based "two-way" integrated development environment (IDE). (See Figure 1, below) Developers can configure graphical elements within the GraphQL Editor IDE to create visual GraphQL entities that will also be rendered as code in the GraphQL Type Language right within the IDE. Also, developers can work the other way and create the entity in code and have it rendered graphically in the Object Palette. (You can view the example shown in Figure 1 directly in GraphQL Editor by going here.)
Figure 1: When you add GraphQL code on the left (1) and click the Generate button (2) the updates will appear in the GraphQL Editor visual UI.
Support for Creating GraphQL Entities
GraphQL Editor's graphical editing capabilities accommodate creating custom scalars and GraphQL directives as well as the root operational types query, mutation, and subscription. In addition, GraphQL Editor supports the graphical creation of interfaces. Once an interface is created, it can be implemented either in a type using code or with the GraphQL Editor Object Palette as shown below in Figure 2. (You can view the example shown in Figure 2 directly in GraphQL Editor by going here.)
Figure 2: GraphQL Editor provides the ability to graphically declare a GraphQL interface (1) and bind it to a type (2) all of which is reflected in code (3).
Structure of the UI
As mentioned above, the GraphQL Editor UI is organized to allow developers to work with a GraphQL in terms of code as well as using its graphical representation of GraphQL elements. (See Figure 3, below).
Figure 3: The GraphQL Editor is UI presents a GraphQL API in terms of code and graphical elements
There's the main Object Palette (Figure 3, callout 1) which is where developers can create the usual GraphQL entities such as types, queries, subscriptions, scalars and such. There is the Code Pane (2) that allows developers to work with GraphQL API entities directly in GQL. Also, there's the Object Palette Navigator (3) that makes it so a developer can traverse regions in the Object Palette visually.
Navigating the UI
There are two ways you can move through the GraphQL Editor's graphical UI. One way is to use the tool's Object Palette Navigator to move about the visual schema. The other way is to move through the Object Palette itself by pressing down on your mouse and moving about. You can also zoom in and out of the Object Palette by moving the scroll wheel on your mouse up and down. (See Figure 4, below)
Figure 4: Moving the GraphQL Editor Object Palette Navigator (1) allows users to navigate around the Object Palette (2).
While you can move the Design Palette around directly by holding your mouse button down and moving your mouse around to get to off-screen items of interest you want to view, as we mentioned above, the Object Palette Navigator allows you to move directly to a region of the palette that's off-screen. The following short screencast demonstrates how the two navigation techniques work.
Importing and Exporting Schemas
Figure 5: GraphQL Editor allows developers to import a pre-existing schema into a project as well as export a current project into one of a variety of file formats. (1).
The import feature makes it so developers can leverage pre-existing work and the export feature allows developers to make their work available to others either as a stand-alone file or more importantly, as an asset that can be stored in a source control management system such as Git.
GraphQL Editor Helpers
GraphQL Editor has a particular mechanism for implementing interfaces and applying directives. This mechanism is called a helper. (See Figure 6, below)
Figure 6: GraphQL Editor's helper feature makes it so that interfaces and directives can be bound to type implementation.
The way a helper works is when a developer wants to associate a type to a GraphQL interface or directive, he or she will select a type in the Object Palette (Figure 6, callout 1) and then choose from one of the helpers that appear in the subsequent menu. (2) Selecting a helper's menu item reveals another menu item from which the developer can choose Directives or Implements. (3) Selecting Directives allows the developer to apply a pre-existing GraphQL directive to the originally selected type. Selecting Implements allows the developer to associate the originally selected type with a pre-existing interface. Of course, the developer always have the option using the Code Pane to apply directives and implements interfaces.
The creators of GraphQL Editor have gone to the trouble of integrating it with GraphiQL, an open-source interactive GraphQL utility from the GraphQL Foundation that, among other things, can provision and render a Web UI to a GraphQL API. GraphQL Editor ships with an integration of GraphiQL that will render a GraphQL API under development with mock data. GraphQL Editor essentially feeds the design of the API-under-development into GraphiQL and then launches the developer into GraphiQL's React-based environment as though it were an API playground that's pre-populated with mock data for testing and validation purposes.
Figure 7: GraphQL Editor's deploy and run as mock backend features (1) allows a mocked version of a GraphQL API to run under the product's GraphiQL web server (2).
Once an API under development is to the point where it has at least a single query defined within a schema, the developer clicks the Deploy mock backend icon, (Figure 7, callout 1) which invokes the code in the Code Pane to a backend GraphQL server that is presented in a GraphiQL UI. The code will be executed using automatically generated mock data. The mock data are random values generated according to the data type. The mocking engine used to generate the data is the Node.js NPM package, faker. Also, the API's schema documentation is presented within the GraphiQL web page too.
GraphQL Editor supports API stitching. This means that a developer can import schemas from other projects and use the types declared within the imported schema in the current projects. (See Figure 6, below.)
Figure 8: GraphQL Editor allows a developer to search for (1) and retrieve schemas (2) that can be used in the current project (3).
The way schema stitching works is that during the project creation or editing process, a developer can search other for projects within the GraphQL Editor ecosystem that might be useful to import into the current work. As shown in Figure 8, callout 1, the developer just needs to invoke the FIND PROJECT TO STITCH search box. GraphQL Editor makes all public projects available for schema stitching. The developer will select the project of interest (2). It will then be added to the ADDED SCHEMAS list. (3). The developer then saves the project. Then, all the types from the schemas included in the ADDED SCHEMAS list will be available to the GraphQL API under development.
In addition to the aforementioned public projects, GraphQL Editor allows users to create projects that are private. Private projects are a feature offered in GraphQL Editor's paid subscription for teams which as of this writing cost $79 USD a month. Once a team subscription is purchased, the subscription owner can add and remove members and thus control access.
Learning and Support Features
GraphQL Editor provides a number of features intended to help users learn to use the product better. Also, the tool ships with support features that enable users to get support from within the tool and online. The details are discussed below.
GraphQL Editor has a name-checking feature that inspects a developer's GraphQL code to ensure that fields are associated with known types. As you can see in Figure 9 below there is an error in PersonalInterface declared at the bottom of the Code Pane (1). The error is detected at design time and reported at the top of the Code Pane (2) along with a suggested correction.
Figure 9: GraphQL Editor can detect undefined types (1) and recommend a correction (2).
Name Checking is a useful feature that can save time when troubleshooting.
GraphQL Editor ships with a set of interactive tutorials embedded directly into the tool's UI. (See Figure 10, below.)
Figure 10: GraphQL Editor provides a number of interactive tutorials as shown on the left that teaches users how to use various features.
The tutorials are rudimentary but are helpful in getting those new to GraphQL Editor up and running quickly.
Given that the GraphQL Editor tool is an open-source project, expertise about the product is not limited to personnel within the company. To facilitate knowledge transfer at a broader level, GraphQL Editor integrates access to the community's Slack channel directly into the UI. (See Figure 11, below.)
Figure 11: Clicking the icon on the upper left (1) will take users to the GraphQL Editor Slack channel web page (2).
Accessing the community Slack channel requires nothing more than clicking the Slack Icon in the GraphQL Editor UI ( Figure 11, callout 1). Clicking the icon retrieves the community's Slack web Page in a separate window. (2)
Incorporating the GraphQL Editor community Slack channel as a general support tool right within the UI provides access to a larger number of experts from which to get help. It's a clever approach to providing online help.
Another support feature found in the browser-based interface is a Chat icon that provides a chat connection to GraphQL Editor personnel. But, be advised that chat is a convenience feature. It is NOT a 24/7 service. The availability of personnel was sporadic during our testing of the product.
Looking to the Future
No piece of software is perfect. In fact, if you look at the evolution of mainstream tools and technologies, reliability and maturity seem to set in at around the third version of a particular product. The folks at GraphQL Editor realize the evolutionary process of software development. In the spirit of continuous improvement, they've identified some shortcomings in the current version of GraphQL Editor which will be addressed in the next version of the code which is scheduled for release around the end of October 2019.
The following is a description of the new features that will be part of the next release.
Need for Two Way Navigation between Code and UI
Most commercial implementations of GraphQL can involve tens maybe hundreds of entities. Figure 12 below shows the rendering of a fairly modest demonstration GraphQL API, IMBOB in GraphQL Editor.
Figure 12: Finding an item of interest in the GraphQL Editor object palette can be difficult.
As you can see there are a lot of objects displayed. While it's easy to find a particular object of interest in the left side code pane using a browser's word search capability, find the item of interest in right side graphical UI is a daunting task.
Presently GraphQL Editor does provide the capability to search on the graphical UI to find an item of interest. Nor can you click on an item in the graphical UI and see the corresponding entry in the left-side Code Pane automatically. Presently the only way to find an item of interest in the object palette is to move the UI inspector in the upper right of the GraphQL Editor UI around until the item of interest appears. When you have something on the order of a hundred elements displayed this can be a time-consuming task.
According to the principals at GraphQL Editor, the next version of the tool will support two-way navigation between code and the graphical elements. Click on code in the Code Pane and you will be brought to the associated object in the Object Palette. Click on an item in the Object Palette and you will be taken to that item's representation in the Code Pane.
This feature will be a significant time-saver.
Make the Automatic UI Rendering Behavior More Predictable
Referring back top GraphQL Editor's Visio block diagramming-like capability, the ability to create a layout of all your GraphQL entities is a very appealing feature. And even better, much the way Visio once worked, you can manually reorganize the layout in a way that makes for a sensible diagram to anyone preferring a visual representation of the project. However, one of the current problems with GraphQL Editor is how the automatic (re)generation feature completely rerenders the current layout in the Object Palette, essentially undoing any changes that you may have manually applied to the layout (eg: maybe you like to visually group together entities of a certain type). For example, one can be working in the Code Pane on a type that appears at the lower part of the Object Palette. In order to apply the changes made in the code to the associated type visually rendered in the Object Palette the developer needs to click the Generate button.
Clicking the Generate button will indeed apply the changes to the visual types represented in the Object Palette, but, in our tests, it also moved the entity to another location in the Object Palette. Sometimes the new location will be outside of the current screen view. Thus, the developer needs to use the Object Palette Navigator to search around the Object Palette to find the new location of the type. This is time-consuming and it's frustrating.
The good news is that the next version of the tool will reportedly address this problem. In the next version, when the user makes a change in code and strikes the Generate button, the affected type will appear where expected, viewable in the Object Palette. We look forward to this improvement.
Two Fundamental Challenges
There are two challenges around using GraphQL Editor that need to be addressed. Addressing these challenges go beyond the scope of simply releasing versions that address particular issues.
Defining the Intended User
The first challenge is that in its current state, GraphQL Editor is not well suited for use by those new to GraphQL. While the tool does provide many features that teach developers how to use the tool itself, it does not provide in-depth integration with information that helps novices learn not only about GraphQL Editor but also about GraphQL as a technology overall.
There is a good argument to be made that requiring a prior understanding of GraphQL in order to work effectively with GraphQL Editor is more a feature than a challenge. Most tools that are meant to be used with a complex technology require deep a priori knowledge. However, given that the folks at GraphQL Editor have already demonstrated an aptitude for integrating third-party assets into their tool in order to enhance the GraphQL Editor developer experience, providing a greater degree of integration into the educational aspects of working with GraphQL is an achievable goal should they so desire to make it happen.
Presently the intended user is unclear. The product's documentation does not state directly what a user needs to know in order to work productively with GraphQL Editor. Without such clarity, those new to both GraphQL and GraphQL Editor might find the developer experience a frustrating one.
Addressing the Random Runtime Errors
GraphQL Editor has a number random of errors that seem to come out of nowhere at runtime.
At the present time, the source code for GraphQL Editor does not appear to have any unit or UI tests. Testing a product such as GraphQL Editor goes well beyond the methods that are typical for testing data-driven applications. GraphQL Editor is a visual software development tool. There's a lot going on in its UI that is hard to capture in an automated fashion. A good deal of human inspection is still necessary. However, moving beyond human testing will become critical as the codebase grows in size and complexity. It will be interesting to see how the GraphQL Editor development community addresses the need. It's an important challenge to be met in order to project to be viable in the long term.
When asked to comment on the issue, Artur Czemiel, CEO of GraphQL Editor responded,
"When doing open source software, you need to gather all the information from the community. As the community is growing, the people are helping us to spot bugs like this. And of course in this big open-source software bugs just happen. You just can't stop this. But the more people we have in our community, the more bugs we can repair."
Czemiel's response is reasonable. Hopefully, the GraphQL Editor community will make greater effort to apply the full breadth of formal application testing to its release process. This means including the testing code directly in the codebase and making it so that developers can run tests a comprehensive set of tests — from unit to integration — upon checkout from GitHub.
Putting It All Together
Making graphical software development tools is hard work, usually requiring the sort of resources found in very large companies. For example, Visual Basic, one of the early giants of graphical programming tools, took years of work before the software giant Microsoft (already experienced in GUIs) brought it to market. GraphQL Editor has a small development staff and a somewhat larger open-source community of developers. They have undertaken a herculean mission that few others would dare. The company is to be commended for committing to its vision.
GraphQL Editor is a tool with promise. The talent and sense of mission driving the company are impressive. We look forward to future versions of the tool that meet the challenges at hand particularly around implementing comprehensive testing. This will ensure the quality of an increasingly complex and continuously growing codebase. As GraphQL Editor continues to follow the path of continuous improvement, there is little doubt that it will prove to be an important tool on the GraphQL API development landscape.