Author: Christoph Thiede

A few days ago, Chris Muller announced the immediate availability of GraphQL for Squeak, a package that allows efficient data query and manipulation within the Squeak environment using the powerful GraphQL language. This release introduces a comprehensive implementation of the GraphQL specification, opening another door for Smalltalk developers to create flexible, performant applications with real-time capabilities.

What Is GraphQL?

GraphQL is an API query language that allows clients to request precisely the data they need, and nothing more. Unlike traditional REST APIs, where multiple endpoints return fixed data structures, GraphQL provides a single endpoint and a flexible query system. This system empowers clients to define the structure of the response, making it highly efficient and tailored to their needs.

GraphQL is particularly well-suited for applications that require real-time data updates and complex queries. It supports features such as strong typing, relationships between data types, and aggregating multiple resources into a single query. These characteristics make GraphQL a great fit for building robust servers and clients in Squeak, particularly when dealing with complex domain models and the need for real-time data synchronization.

Introducing GraphQL for Squeak

The GraphQL implementation for Squeak, developed by Chris Muller, strictly adheres to the current GraphQL specification (October 2021) and is made available under MIT license. This is a complete implementation. Every grammar, validation, and execution rule defined in the specification is covered by at least one test case. The framework integrates seamlessly with Squeak.

Key Features:

• Complete GraphQL Specification Compliance: The implementation covers every aspect of the GraphQL specification, ensuring that your applications can utilize all features, including asynchronous subscriptions.
• Documentation and Examples: Included help pages illustrate working examples, making it easy to get started and explore the capabilities of the framework.
• Modular and Extensible: Type systems (and their associated resolvers) can be defined and assembled into complete applications.
• Custom Scalar Types and Directives: Several additional custom scalar types and powerful directives are included to enhance your development experience and streamline common tasks.

Interoperability Is King

One benefit of GraphQL is how conformance to a standard fosters greater interoperability between not only systems but the groups surrounding them: whether between users and developers, organizations and their customers, or front-end and back-end technologies – GraphQL optimizes the right separations of concerns.

For example, having a standard way to inspect the schema of a live GraphQL-based system opens possibilities for automated cooperation that are impossible without a standard. As organizations publish their GraphQL schemas, implementers can help optimize their customer-facing experience with tools that capitalize on the features of GraphQL. GraphQL allows certain elements like type and field definitions to have integrated markup “documentation” which could be rendered in user interfaces, or as a page in a generated “help” compendium. The possibilities are limitless.

Being able to easily parse and interact with other organizations’ GraphQL schemas directly in the image could open new potentials for integration. Exploring the following expression lets one browse the type definitions and directives of the GitHub GraphQL API:

GqlParser parse:
	(WebClient httpGet:
		'https://docs.github.com/public/fpt/schema.docs.graphql') content

Try It Out!

Install the GraphQL package into Squeak Trunk by selecting the (head) version of the project from the SqueakMap window (available via the Apps menu of the world main docking bar).

Alternatively, simply execute this in a workspace:

Installer new merge: #graphQlTestsEngine

To verify the installation, tests can be found under the GraphQL-* packages in the TestRunner (available under the Tools menu).

To get started, you can run the following snippet, which creates a small but complete GraphQL engine for searching all classes in the system for certain names.

| system engine |

"Define a small type system and its resolver."
system := GqlSystemDefinition
	typeSystem: '
		type Class {
			name : String!
			superclass : Class
		}
		type Query {
			findClasses(pattern : String) : [Class!]!
		}'
	resolver: 
		(GqlCraftedSchemaResolver new map: {
			{ 'Query'. 'findClasses'. SystemNavigation. #allClassesAndTraitsMatching:. #('pattern') }.
			{ 'Class'. 'name'. Class. #name }.
			{ 'Class'. 'superclass'. Class. #superclass }
		}).

"Instantiate the engine, supply a domain provider."
engine := GqlEngine
	systemDefinition: system 
	providers: {self systemNavigation. nil. nil}.

"Execute the only possible query, request the name and the superclasses' name for each result."
(engine execute: '{
	findClasses(pattern: "*Collection") {
		name
		superclass { name }
	}
}') response data

This query will return the following JsonObject:

Help Is Available

After loading the package, a “GraphQL” section will also become available in Squeak’s Help Browser (available via the help menu in the docking bar), where you can find detailed guidance and more complex examples to experiment with.

Roadmap

The next step is a networking package to accept GraphQL requests sent from a client to a server and return the JSON responses. This is well underway and planned to be released soon.

Happy Squeaking!

Authors: Chris Muller and Christoph Thiede