Architecting flexible back ends with GraphQL

As businesses traverse the complexities of the digital landscape, the seamless integration of diverse systems has emerged as a key element in driving business success. However, traditional integration approaches, burdened by their reliance on fixed data schemas, often make it harder to keep up with the demands of modern applications.

Taking a more modern approach to data access can make all the difference. By adopting GraphQL, organizations can design more flexible, scalable, and responsive back-end systems to extract maximum value from their data, fostering innovation and differentiation in the marketplace.

Example scenario: Travel management system

Let’s take an example of a hypothetical travel management service named TravelTracker.

TravelTracker is an application designed to streamline the travel experience by providing users with personalized services based on their profile preferences, travel history, and loyalty points. This system manages user profile data, catering to personal information and travel preferences. User profile data is stored in a highly scalable NoSQL database for rapid retrieval and updating.

The travel history database records users’ past travel activities, including details of previous bookings such as flights, hotels, car rentals, and tour packages. With the integration of the loyalty program, users’ mileage balances, points earned, elite status levels, and available rewards are obtained from various loyalty program providers.

WSO2

In a system like this, defining the proper API architecture is critical. API architecture is the foundation of how various software systems interact. It’s not just about establishing a connection; it’s about setting the rules and paving the way for reliable and flexible communication within a software ecosystem.

The most common architectural styles, such as REST, GraphQL, WebSocket, Webhooks, RPC, SOAP, etc., present unique API design approaches. Selecting the appropriate API style involves considering factors such as project requirements, performance considerations, client needs, and ecosystem compatibility to ensure that the chosen architecture aligns with the goals and constraints of the project.

Let’s explore how the popular REST-based design tackles the problem and examine if GraphQL provides a better alternative.

API design with REST vs. GraphQL

Let’s examine the API design within the TravelTracker example. Imagine the initial dashboard view of the application presents a summary view that includes the important user profile data, latest travel history, and top loyalty data for the user who is currently logged in.

With a REST API approach, the required data needs to be gathered by accessing multiple endpoints. So, these endpoints can be defined as follows:

• /users/<id> endpoint to fetch the user profile data.
• /users/<id>/history endpoint that returns a user’s travel history.
• /users/<id>/loyalty endpoint that returns a list of loyalty account details.

WSO2

With the GraphQL approach, a single query can be sent to the server, specifying the exact data needed. The server then replies with the requested data.

WSO2

GraphQL is the better REST

GraphQL, introduced by Facebook in 2012 and publicly released in 2015, is an application-layer protocol designed to enhance RESTful API calls. It functions as both a query language for the API and a server-side runtime, executing queries based on a defined type system for the data.

Although REST is widely favored for its simplicity, broad adoption, and compatibility with existing infrastructure, GraphQL presents numerous advantages over REST.

GraphQL offers more flexibility over the data, avoiding the common issues of data over-fetching and under-fetching. Through its query capabilities, client applications can precisely specify the required data, eliminating the need for multiple network calls. This not only enhances GraphQL API performance but also resolves issues related to bandwidth efficiency. Additionally, clients can iteratively develop personalized user interfaces by requesting additional specific data sets without any changes in the API level.

GraphQL has a strongly typed schema that precisely defines the available data and its structure, reducing the likelihood of inconsistencies during data retrieval. Schemas serve as the single source of truth for the API, which is helpful for API consumers. They enable powerful tool support, including auto-generated documentation, type checking, and IDE integration. This enhances the developer experience and facilitates the development process by providing valuable insights and assistance.

Each resource in a RESTful API is identified by a unique URL, which makes the API intuitive and easy to understand. GraphQL APIs typically expose a single endpoint that accepts queries, mutations, and subscriptions. This introduces greater complexity, but simplifies client-server communication and reduces the need for multiple endpoints, leading to a more streamlined architecture. It also improves the API’s maintainability.

REST vs. GraphQL: Making the right choice

Determining whether to use REST or GraphQL depends on various factors, including project requirements, development team expertise, and specific use cases.

REST is more suitable for the following scenarios:

• If the application has straightforward data needs, REST may be a suitable choice. RESTful APIs are well-suited for CRUD (create, read, update, delete) operations on resources with predictable data structures.
• Due to their stateless nature, REST APIs work well with caching mechanisms. If the application requires extensive caching of responses to improve performance and reduce server load, REST might be a better option. Caching in GraphQL is possible, but it can present challenges due to its flexible nature and the granularity of data retrieval.
• If the project needs to integrate with existing systems or services that already expose RESTful APIs, sticking with REST can simplify integration efforts and ensure compatibility with established workflows.

GraphQL becomes more suitable for these scenarios:

• If the application has complex data requirements or needs to fetch data from multiple sources in a single request, GraphQL’s flexible querying capabilities make it a compelling choice.
• If the primary objectives involve empowering clients to request only the data they require and ensuring the adaptability of the API to evolve without disrupting existing clients, then GraphQL emerges as the preferred choice. This stands as a significant advantage, particularly in scenarios where the client application operates on slow mobile networks or is utilized by users in remote regions with less consistent connectivity.
• If there’s a need to accommodate various clients through the same API, each with distinct data needs, GraphQL stands out as the superior option. It adeptly handles diverse client requirements via a single API endpoint, ensuring no disruptive changes affect existing clients. This flexibility is especially beneficial in maintaining seamless service across multiple platforms or versions.

Build a GraphQL service with Ballerina and Choreo

There are several programming languages and integration products commonly used to develop GraphQL-based solutions. Choosing the correct programming language or integration product is crucial for developing a GraphQL application that meets the needs and performs optimally. When selecting, consider factors such as the development team’s expertise, project requirements, performance considerations, community support, and ecosystem compatibility.

Ballerina is an open-source, cloud-native programming language optimized for integration. Developing a GraphQL service with Ballerina involves leveraging its built-in features for seamless API development and integration. Once the development phase is done, GraphQL applications can be deployed using deployment technology such as VMs or Kubernetes. It is also possible to use Choreo as the internal developer platform to deploy and govern the cloud-native GraphQL applications while reducing time to market.

Schema design with the Ballerina type system

Ballerina supports both code-first and schema-first approaches when developing GraphQL services. With Ballerina’s rich type system support, defining types and fields that reflect the application’s data model is very intuitive. The GraphQL service designer will simplify the understanding and navigation of complex GraphQL services and allow the developer to browse them effortlessly without examining the code directly.

Resolver implementation with Ballerina services

The built-in Ballerina services support allows developers to write resolvers to handle GraphQL queries, mutations, and subscriptions using familiar programming language syntax. This allows developers to focus on business logic and removes any protocol-related burden.

Testing with the Ballerina test framework and client tools

Ballerina’s test framework provides comprehensive testing capabilities, including mocking, assertion, and coverage analysis, to validate the behavior of the GraphQL services, such as resolvers and error handling. The Ballerina GraphQL module includes a built-in GraphiQL client to test the GraphQL APIs using the GraphiQL IDE.

Documentation and schema generation

The Ballerina document framework allows you to document types, fields, queries, mutations, and subscriptions in the schema using Ballerina’s doc comments. That will generate interactive API documentation using Ballerina’s built-in documentation generation tools, making it easy for clients to understand and interact with the GraphQL service. Also, Ballerina’s GraphQL tool provides capabilities to generate GraphQL schema for a given Ballerina GraphQL service.

Advanced GraphQL features

Additionally, Ballerina has advanced GraphQL features, such as built-in support for GraphQL caching, federation, and data loader mechanisms, seamlessly integrated into its ecosystem, allowing developers to architect robust and efficient GraphQL APIs effortlessly. Security measures to protect the GraphQL service can be implemented using Ballerina’s built-in security features, such as OAuth and JSON Web Tokens.

Deployment with Choreo

Finally, the GraphQL service can be deployed to a production environment using Choreo. Choreo is an internal developer platform as a service that streamlines the process of designing, developing, deploying, and managing cloud-native applications.

Choreo enables easy deployment of applications onto popular cloud platforms like AWS, Azure, Google Cloud, and more. Choreo handles CI/CD, deployment, scaling, and monitoring, ensuring high availability and reliability in production environments. In addition, Choreo has an integrated GraphQL Console to test publicly exposed GraphQL endpoints.

Flexible, scalable, responsive

As businesses navigate the digital landscape, the demand for seamless system integration is increasing. GraphQL enables organizations to architect more flexible, scalable, and responsive back-end systems. Using TravelTracker as an example, we’ve seen how GraphQL’s querying capabilities streamline data retrieval, addressing issues like over-fetching and under-fetching. Leveraging the capabilities of Ballerina and Choreo further enhances GraphQL development, offering seamless integration and streamlined deployment.

Anupama Pathirage is a director of engineering for integration at WSO2. Prior to joining WSO2, Anupama worked at DirectFN (Pvt.) Limited as an associate technical lead where she was responsible for researching, designing, and developing enterprise-level low-latency applications in the financial services and capital market industries. She holds a master’s degree in computer science (specialized in software architecture) and a BSc first class degree in computer science and engineering from the department of computer science and engineering, University of Moratuwa, Sri Lanka.

—

New Tech Forum provides a venue for technology leaders—including vendors and other outside contributors—to explore and discuss emerging enterprise technology in unprecedented depth and breadth. The selection is subjective, based on our pick of the technologies we believe to be important and of greatest interest to InfoWorld readers. InfoWorld does not accept marketing collateral for publication and reserves the right to edit all contributed content. Send all inquiries to doug_dineley@foundryco.com.