Configuration sync & release pipeline

ApiGo's API configuration does not act on live traffic directly. For an API to go from "design-time" to "callable", it must pass through: save the API definition → generate a development environment release snapshot → sync to the target environment → write to the Redis runtime → notify the gateway to refresh. This page explains the data flow, cache structures and failure fallbacks along this pipeline.

Design-time and runtime states

State	Storage location	Content	Who reads it
Design-time	MySQL base_api_info	Complete API definition: SQL/proxy configuration, parameters, plugins, groups	Admin edit page
Release state	MySQL base_api_release	Immutable snapshot for a specific environment and revision number	Release management, runtime construction
Runtime	Redis	Route definitions, API details, flow control/circuit breaking/cache/IP rules, app keys, subscription status	Gateway, execution service

Changes in design-time do not affect released APIs. Only after you perform "Release" or "Sync" do changes enter a snapshot and get synchronized to the runtime.

Release snapshot model

Key fields

Field	Meaning
sourceApiId	Design-time API ID that the snapshot originates from; snapshots of the same API in all environments share this value
apiLinkId	Version family ID. After an API is copied or migrated, it can still be traced back to the same family, which is used to calculate revision numbers
envCode	Environment code; dev is the development environment, and all others are custom environments
deployRevision	Revision number, monotonically increasing within the same apiLinkId; comparing revision numbers across environments determines whether a sync is needed
isCurrent	The snapshot currently in effect for the environment; only one snapshot per API per environment can be 1
apiPath	Actual access path with the environment prefix already joined
enabled	Online/offline status, carried over from design-time during sync

Release actions

1. Release to the development environment: each release locks the version family root node, calculates a new revision number, generates a new snapshot, and sets isCurrent of the old snapshot to 0.
2. Sync to the target environment: compares the deployRevision of the target environment's current snapshot with the current revision number of the development environment.
   • Same: return directly without generating a duplicate snapshot.
   • Target environment already has a snapshot with the same revision number: reuse that snapshot and switch it to the current version.
   • Otherwise: generate a target environment snapshot using the development environment snapshot as the template, and reassemble the target environment path prefix.
3. Rollback: set a historical snapshot in the target environment back to isCurrent=1 and refresh the runtime.
4. Delete an environment version: delete the target environment snapshot and refresh the runtime; a development environment version cannot be deleted separately, and the source API must be deleted instead.

Special nature of development environment snapshots

Development environment snapshots represent the "latest runnable version". When syncing to a target environment, the system first ensures that a current snapshot exists in the development environment, then uses it as the template. Therefore, an API that has never been released cannot be synced to other environments.

Runtime construction

The admin-side ApiRuntimeCacheService is responsible for converting release snapshots into runtime data:

Route definitions

Routes are written to Spring Cloud Gateway's native Redis route repository, with the key routedefinition_<routeId>:

• routeId takes the route ID configured in the release snapshot first; if there is none, the API ID is used; if there is still none, a UUID is generated.
• The predicate is fixed to Path + Method, preventing same-path APIs with different methods from overwriting each other.
• The upstream address is lb://<service-name> (microservice mode) or the configured execution service address.
• Parameters such as timeout and retry come from the API definition and global configuration.

Rule storage

Rule	Redis structure	Dimension
Flow control	Hash crabc_flow_rule	Gateway routeId
Circuit breaking	Hash crabc_degrade_rule	Gateway routeId
API cache	Hash crabc_api_cache	API / route
IP rules	Hash	API detail dimension

Flow control and circuit breaking rules use the route ID as the Hash field, not the API ID. The reason is that one API may correspond to multiple routes in different environments and under different release paths; only by distributing rules at the route level can they hit precisely.

Change notification mechanism

Event structure

Each time the admin side modifies runtime data, it publishes a CacheChangeEvent through Redis Pub/Sub:

Field	Description
resourceType	Resource domain: ROUTE, API_DETAIL, FLOW_RULE, DEGRADE_RULE, CACHE_RULE, IP_RULE, APP_KEY, SUBSCRIPTION, DATASOURCE, SKILL_DETAIL
changeAction	UPSERT / DELETE / REFRESH
version	Resource domain version number, incremented on each release
resourceIds	Affected resource IDs; empty for REFRESH means a full refresh
source	Event source, for troubleshooting

The channel is crabc_change_notify, and the version key is crabc_change_version:<resourceType>.

Gateway handling

RedisMessageListener dispatches by resource domain:

Event	Gateway action
ROUTE	Publishes RefreshRoutesEvent and re-reads routes from Redis
FLOW_RULE / DEGRADE_RULE	Incrementally updates the local rule snapshot and calls Sentinel loadRules
API_DETAIL / CACHE_RULE / IP_RULE	Clears the API detail cache; when IDs are present, invalidates only the corresponding APIs, and on REFRESH, clears everything
APP_KEY	Clears the app and tool list cache
SUBSCRIPTION	Clears the subscription runtime cache

Ordering and idempotency

Events carry a version number, and the gateway records the latest processed version for each resource domain:

• Events with a version number less than or equal to the processed version are discarded, preventing network retries or out-of-order delivery from overwriting new state with old data.
• Incremental events invalidate precisely by resourceIds, avoiding clearing caches of unrelated APIs.
• REFRESH semantics are used for full rebuilds and do not depend on specific IDs.

Failure fallbacks

Pub/Sub provides "at-most-once" semantics, and network jitter may drop messages. The system provides two layers of fallback:

1. Scheduled version reconciliation: the gateway reads the latest version number of each resource domain every 5 minutes and compares it with the locally processed version; when it finds itself behind, it re-subscribes to the channel and rebuilds according to REFRESH.
2. Manual reconciliation: the admin-side ManualReconcileService can resend REFRESH events for API_DETAIL, ROUTE, FLOW_RULE, DEGRADE_RULE, CACHE_RULE and IP_RULE, for troubleshooting anomalies after a release.

Delay before changes take effect after release

Normally, changes take effect within seconds. If "released but still reports that the API does not exist" occurs, first confirm whether the gateway logs received the change event, then perform manual reconciliation; if it still does not take effect, check whether the corresponding routedefinition_* key exists in Redis.

Data source sync

The data source sync strategy differs from that of APIs:

• The admin side writes the data source configuration (passwords stored encrypted) into the Redis snapshot crabc_data_source, and maintains a snapshot timestamp field.
• The snapshot uses atomic replacement, preventing reads of partial data when multiple admin instances refresh concurrently.
• Each Admin instance maintains its own local connection pool; the pool is not rebuilt when the configuration is unchanged, and changes such as password rotation trigger a rebuild.
• Data source changes publish a DATASOURCE event; the execution service clears its local data source cache and re-fetches on demand.

Relationship with the license

License validation is independent of configuration sync: at startup, a failed validation by LicenseStartupRunner directly blocks process startup; during runtime, validation runs on a schedule every 24 hours, and the process exits gracefully if the license becomes invalid (exit code 1). The license does not participate in route or rule distribution. See Deployment topology & license.