GraphQL + Gateway Orchestration for Multi‑Endpoint Enterprise Online Services: Practices and Improvements

When building enterprise‑level, multi‑platform content‑aggregation online services, the conventional RESTful development model often results in a large amount of duplicated API development. This article introduces a practice that combines the GraphQL query language with gateway orchestration to solve the problem of massive repetitive customization.

In early collaborations with automobile manufacturers, Gaode leveraged existing data, engine capabilities, and key CP services (e.g., parking lots, gas stations, weather). The cooperation model provided separate REST APIs for each car maker, project, and terminal. Over time, more than a dozen core data services accumulated, and after 2‑3 years the API count grew to several hundred, continuously expanding and creating significant maintenance challenges.

The development process can be divided into two parts: acquiring business‑related data and providing non‑business capabilities such as authentication. These issues are common to most teams, and typical solutions involve service aggregation, workflow orchestration, and API gateways.

This article briefly introduces the practice of refactoring the legacy architecture of car‑networking online services.

Glossary

GraphQL : a query language for APIs and a runtime for fulfilling those queries. It provides a clear, complete description of the data, allowing clients to request exactly what they need without redundancy, and it evolves easily over time.

DSL : a domain‑specific language, a programming language dedicated to a particular problem domain (e.g., HTML for web pages, Emacs Lisp for Emacs).

API Gateway : a server that acts as the single entry point to a system, similar to the Facade pattern. It abstracts internal architecture, provides customized APIs per client, and can handle authentication, monitoring, load balancing, caching, request splitting, and static responses.

Existing Problems

The previous car‑networking online service architecture suffered from the following issues:

Improvements

The improvement plan focuses on three aspects:

Atomic service capabilities: provide stable interfaces upward while shielding downstream complexity.

Build a query engine: enable powerful query composition to aggregate and customize atomic services arbitrarily.

API gateway plugins: abstract non‑business data capabilities into configurable plugins and orchestrate them via a database‑stored chain.

4.1 Implement Stable, Independently Evolving Atomic Services

We catalog existing services and abstract core capabilities that should be developed, deployed, and evolved independently. The goals are to expose stable interfaces upward and hide underlying data‑access and multi‑source differences, while organically integrating location‑centric capabilities into a complete set of atomic services.

4.2 Transform Custom Code Development into Declarative Query Statements

The aim is to replace custom code for service aggregation and customization with declarative GraphQL queries. Key features include:

Standardized query language exposed upward.

Bottom‑up composition of atomic capabilities.

Extraction of common business patterns, refinement of customization models, and increased reuse.

Directly using GraphQL introduces two main challenges:

Data‑fetch N+1 problem, mitigated by Facebook’s DataLoader with batching and caching.

GraphQL specification limits certain customizations, such as parameter linking, type conversion, output formatting (e.g., timestamps, coordinates), configuration‑driven field depth, and free model relationships.

To address these, a lightweight DSL is embedded to provide:

Built‑in and custom function support.

Dynamic model relationship queries with context‑aware parameters.

Easy extensibility for user‑defined functions.

The DSL must remain simple; overly complex DSLs would defeat the purpose of replacing code with queries.

5. Business‑Irrelevant Functions Configured via API‑Gateway Plugins

Previously, each API mixed business logic with cross‑cutting concerns (authentication, response formatting). After the first refactor, non‑business functions are abstracted into a processing chain where each node can have multiple implementations (generic or customized). The chain configuration is stored in a database and applied at runtime.

Authentication plugins vary per client:

HTTP signature for B2B requests.

JWT for in‑vehicle or mobile terminals.

API Key.

These plugins share the same gateway infrastructure; differences lie in configuration (e.g., JWK refresh strategies, JWT verification policies).

The gateway also implements transformers to convert GraphQL output back to REST APIs, supporting legacy compatibility and customer‑specific response formats:

Parameter transformation: fill GraphQL templates with REST parameters.

Header transformation: adapt to different client specifications.

JSON transformation: handle varying response structures and custom non‑standard interfaces.

6. Summary

Through the described refactor, the car‑networking online service development model has been upgraded to a dynamic API console with the following benefits:

Development efficiency: orthogonal composition of atomic capabilities replaces custom code; custom development share drops by ~60%; a single interface now takes 2‑3 person‑hours instead of 2‑3 person‑days.

Protocol compatibility: a hybrid REST solution provides standard interfaces while preserving legacy compatibility.