Apicurio Registry

Where groupId and artifactId identify the registry artifact. Both are optional for operations that do not require them (e.g., searchArtifacts, createGroup).

The first / separates the group ID from the artifact ID. Group IDs containing / cannot be represented in the URI path. Producers can instead supply the group ID using the CamelApicurioRegistryGroupId header, which overrides the URI value.

Camel components are configured on two separate levels:

The Apicurio Registry component supports the following options which are listed below.

The Apicurio Registry endpoint is configured using URI syntax:

With the following path and query parameters:

The Apicurio Registry component supports the following message header(s), which is/are listed below:

The producer supports the following operations, set via the operation endpoint option or the CamelApicurioRegistryOperation header:

Artifact content supplied to createArtifact, updateArtifact, validate, and testCompatibility is converted to a string for the SDK’s VersionContent model. Its content type is taken from the CamelApicurioRegistryContentType header. Without the header, it is derived from the content: application/json when it starts with { or [, application/xml when it starts with <, application/x-protobuf or application/graphql for PROTOBUF and GRAPHQL artifacts, and application/x-yaml otherwise (for example OpenAPI or AsyncAPI documents written in YAML). For AVRO and PROTOBUF, supply the schema definition, rather than serialized message data. getArtifactContent returns a byte[]; the component closes the SDK response stream before passing the content to the route.

validate and testCompatibility check a proposed artifact version against the registry’s configured rules without storing it. They do not validate application messages against a stored schema. Authentication, connectivity, and other non-rule failures propagate as exceptions, rather than returning a negative validation result.

Both operations set CamelApicurioRegistryValidationErrors to the rule violation details when a check fails and clear any previous value before checking. Both set CamelApicurioRegistryValidationResult; testCompatibility also returns the boolean result in the body, while validate preserves the body.

Operations that act on a specific group or artifact fail with an IllegalArgumentException when the group or artifact ID is set neither in the endpoint path nor in a header.

The consumer polls the registry for new versions of the specified artifact. It tracks the last seen globalId and only delivers new versions. Set the delay option to control the polling interval (default: 500ms).

On first start, all existing versions of the artifact are emitted as exchanges. Subsequent polls only deliver versions created after the consumer started. The watermark is held in memory and resets on route/context restart.

Once it has a watermark, each poll first asks only for the newest version, so an idle poll transfers a single entry. When there is something new, the consumer requests versions newest first, one page at a time, and stops at the first version it has already seen. Paging is offset-based: if a version is deleted while the consumer is reading pages, an older new version can move to a page that was already read and be skipped.

All version states are listed, so DRAFT versions are delivered as soon as they appear. If the registry allows changing the content of a version, a version is not delivered again after its content changes. With fetchContent=true, DISABLED versions are skipped, because the registry does not return their content. If the content of a version is not found (HTTP 404), the consumer retries it on later polls, since a registry node with replicated storage may not have the version yet; if it is still not found once at least one polling delay has passed (also with greedy=true), the version is skipped with a warning. Skipped versions are not delivered again, even if a disabled version is enabled later.

If fetching content fails, or the route fails to process a version (including failures handled by the error handler without being rethrown, such as with the default error handler), the consumer stops the current poll without advancing the watermark. The failed version and any newer ones are delivered again on the next poll. A version that always fails therefore blocks newer versions. To skip such a version, mark the failure as handled, which lets the consumer advance past it:

When fetchContent=true, the consumer fetches the version content and sets it as a byte[] exchange body, closing the SDK response stream before processing the exchange. Otherwise, the version metadata object is set as the body.

All endpoints of the component share a single Vert.x instance for their SDK clients. The component creates it on first use and closes it when the component stops. To reuse an existing Vert.x instance, set the vertx component option or bind a single Vertx bean in the registry; the component does not close a Vert.x instance it did not create.

A client supplied through registryClient remains caller-owned; the caller is responsible for its underlying HTTP resources.

For HTTPS registries that use a private CA or require client certificates (mTLS), configure sslContextParameters. Use proxyHost, proxyPort, proxyUsername and proxyPassword to go through an HTTP proxy. Both settings also apply to the OAuth2 token endpoint.

The component never follows HTTP redirects, so credentials are never sent to another host. Configure registryUrl with the final address of the registry API.

The producer makes blocking calls. It cannot run on a Vert.x event loop thread, for example in a route started by an event-loop consumer of the same Vert.x instance; it fails with an IllegalStateException there. Hand the exchange to a worker thread first, for example with threads().

The component supports three authentication modes via the authType option:

Example with OIDC: