The Registry Service is the control plane of Spring Middleware. It provides service discovery, tracks clusters and running nodes, and stores metadata such as REST resources and GraphQL schema locations. This allows Spring Boot microservices to remain autonomous while the platform stays discoverable and consistent.
The Registry provides the central source of truth for platform topology and API metadata. It knows which logical services exist, which nodes are currently running for each service, which REST resources are registered, and which GraphQL schemas are available in the platform.
The Registry is not where business logic runs, and it is not where GraphQL queries are executed. It exists to expose accurate topology and metadata so the rest of the platform can route requests, compose schemas, and keep runtime behavior explicit.
The Registry sits in the control plane and exposes the information needed for service-to-service communication, topology awareness, REST inspection, and GraphQL discovery.
The Registry is built around a small set of explicit concepts that define service identity and metadata.
A cluster is the logical service identifier, such as product-service,
catalog-service, or order-service.
In many environments it maps naturally to a Kubernetes Service or a logical service name.
A node is a running instance of a cluster: a pod, container, VM, or bare endpoint. Clusters typically have multiple nodes for scalability and redundancy.
A resource is a registered REST endpoint exposed by a service. Spring Middleware discovers and registers resources from annotated controllers.
A GraphQL schema is registered as metadata describing where the schema lives and which nodes expose it. The Registry stores discovery information, not query execution state.
Two key models define most of the registry runtime view: RegistryEntry and SchemaLocation.
RegistryEntry represents a service registered in the Registry and contains the information
needed for service discovery and endpoint resolution.
clusterEndpoint — logical endpoint or base URL of the clusternodeEndpoints — concrete endpoints for running nodespublicEndpoint — optional externally-facing endpoint
SchemaLocation represents GraphQL schema metadata used for discovery and future schema composition.
namespace — logical schema namespacelocation — schema location referencecontextPath — service context pathpathApi — GraphQL endpoint pathschemaLocationNodes — nodes exposing the schemaThe Registry keeps topology and metadata coherent so the rest of the platform can operate against an explicit runtime view.
Track clusters, nodes, endpoints, and health-related state across the platform.
Provide lookup data for clients such as @MiddlewareClient and platform gateways.
Keep registered REST resources and GraphQL schema locations available for tooling and routing.
Services interact with the Registry as part of startup, registration, and periodic topology consistency checks.
The application context is created and the service runtime starts normally.
Spring Middleware scans registration-related annotations such as @Register.
REST resource metadata and GraphQL schema locations are registered in the Registry.
The running instance registers itself as a node in the cluster.
A scheduler revalidates topology and re-registers or cleans up state when needed.
The communication layer uses the Registry to resolve where calls should go when a declarative client is invoked.
The service attribute on @MiddlewareClient identifies the target cluster.
The communication layer resolves the cluster to a RegistryEntry.
A node selection strategy chooses one of the available node endpoints.
The HTTP request is sent only to nodes considered available by the Registry view.
If the Registry removes a node due to health failure or missing heartbeat, that node is no longer selected for new service-to-service calls.
The communication layer can surface a structured service-unavailable error, including lookup details in the error extensions when relevant.
For GraphQL, the Registry is responsible for schema discovery metadata, not execution.
Services that expose GraphQL APIs register one or more SchemaLocation entries so platform components can discover them later.
A GraphQL gateway can query the Registry for schema locations, load available schemas, and build a unified runtime view across services.
In the repository, the Registry is implemented through a small set of dedicated modules that separate model, service logic, and boot runtime.
Shared data model for registry entries, schema locations, and topology-related structures.
Core registry logic, persistence, service APIs, and topology management behavior.
Boot application that runs the Registry as a standalone infrastructure service.
From the point of view of an application service, the most important concern is how to reach the Registry. Operationally, the Registry should be treated as critical platform infrastructure.