API docs by Redocly

Solace Schema Registry (1.0.0)

Download OpenAPI specification:

License: Solace License

Solace Schema Registry is a datastore for standard event schemas and API designs. Solace Schema Registry enables developers to manage and share the structure of their data using a REST interface. For example, client applications can dynamically push or pull the latest updates to or from the registry without needing to redeploy. Solace Schema Registry also enables developers to create rules that govern how registry content can evolve over time. For example, this includes rules for content validation and version compatibility.

The Solace Schema Registry REST API enables client applications to manage the artifacts in the registry. This API provides create, read, update, and delete operations for schema and API artifacts, rules, versions, and metadata.

The supported artifact types include:

  • Apache Avro schema
  • Google protocol buffers
  • JSON Schema
  • XML Schema Definition

Important: You must prefix all API operation paths with /apis/registry/v3. For example: /apis/registry/v3/ids/globalIds/{globalId}.

Artifacts

The primary way to interact with the Solace Schema Registry API is to add, update, or delete artifacts. This section includes all of these primary operations.

Get artifact by global ID

Gets the content for an artifact version in the registry using its globally unique identifier.

This operation may fail for one of the following reasons:

  • No artifact version with this globalId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
globalId
required
integer <int64>

Global identifier for an artifact version.

query Parameters
references
string (HandleReferencesType)
Enum: "PRESERVE" "DEREFERENCE" "REWRITE"

Allows the user to specify how references in the content should be treated.

returnArtifactType
boolean

When set to true, the HTTP response will include a header named X-Registry-ArtifactType that contains the type of the artifact being returned.

Responses

Response samples

Content type
*/*
{
  "openapi": "3.0.2",
  "info": {
    "title": "Empty API",
    "version": "1.0.0",
    "description": "An example API design using OpenAPI."
  }
}

Search for artifacts

Returns a paginated list of all artifacts that match the provided filter criteria.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
query Parameters
name
string

Filter by artifact name.

offset
integer
Default: 0

The number of artifacts to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of artifacts to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (ArtifactSortBy)
Enum: "groupId" "artifactId" "createdOn" "modifiedOn" "artifactType" "name"

The field to sort by. Can be one of:

  • name
  • createdOn
labels
Array of strings

Filter by one or more name/value label. Separate each name/value pair using a colon. For example labels=foo:bar will return only artifacts with a label named foo and value bar.

description
string

Filter by description.

groupId
string

Filter by artifact group.

globalId
integer <int64>

Filter by globalId.

contentId
integer <int64>

Filter by contentId.

artifactId
string

Filter by artifactId.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Filter by artifact type (AVRO, JSON, etc).

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "count": 0
}

Search for artifacts by content

Returns a paginated list of all artifacts with at least one version that matches the posted content.

This operation can fail for the following reasons:

  • Provided content (request body) was empty (HTTP error 400)
  • A server error occurred (HTTP error 500)
query Parameters
canonical
boolean

Parameter that can be set to true to indicate that the server should "canonicalize" the content when searching for matching artifacts. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner. Must be used along with the artifactType query parameter.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Indicates the type of artifact represented by the content being used for the search. This is only needed when using the canonical query parameter, so that the server knows how to canonicalize the content prior to searching for matching artifacts.

groupId
string

Filter by artifact group.

offset
integer
Default: 0

The number of artifacts to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of artifacts to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (ArtifactSortBy)
Enum: "groupId" "artifactId" "createdOn" "modifiedOn" "artifactType" "name"

The field to sort by. Can be one of:

  • name
  • createdOn
Request Body schema: */*
required

The content to search for.

string <binary> (FileContent)

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "count": 0
}

List artifact references by content ID

Returns a list containing all the artifact references using the artifact content ID.

This operation may fail for one of the following reasons:

  • A server error occurred (HTTP error 500)
path Parameters
contentId
required
integer <int64>

Global identifier for a single artifact content.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List artifact references by global ID

Returns a list containing all the artifact references using the artifact global ID.

This operation may fail for one of the following reasons:

  • A server error occurred (HTTP error 500)
path Parameters
globalId
required
integer <int64>

Global identifier for an artifact version.

query Parameters
refType
string (ReferenceType)
Enum: "OUTBOUND" "INBOUND"
Example: refType="INBOUND"

Determines the type of reference to return, either INBOUND or OUTBOUND. Defaults to OUTBOUND.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List artifacts in group

Returns a list of all artifacts in the group. This list is paged.

path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

query Parameters
limit
integer

The number of artifacts to return. Defaults to 20.

offset
integer

The number of artifacts to skip before starting the result set. Defaults to 0.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (ArtifactSortBy)
Enum: "groupId" "artifactId" "createdOn" "modifiedOn" "artifactType" "name"

The field to sort by. Can be one of:

  • name
  • createdOn

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "count": 0
}

Create artifact

Creates a new artifact. The body of the request should be a CreateArtifact object, which includes the metadata of the new artifact and, optionally, the metadata and content of the first version.

If the artifact type is not provided, the registry attempts to figure out what kind of artifact is being added from the following supported list:

  • Avro (AVRO)
  • Protobuf (PROTOBUF)
  • JSON Schema (JSON)
  • XML Schema (XSD)

An artifact will be created using the unique artifact ID that can optionally be provided in the request body. If not provided in the request, the server will generate a unique ID for the artifact. It is typically recommended that callers provide the ID, because it is typically a meaningful identifier, and as such for most use cases should be supplied by the caller.

If an artifact with the provided artifact ID already exists, the default behavior is for the server to reject the content with a 409 error. However, the caller can supply the ifExists query parameter to alter this default behavior. The ifExists query parameter can have one of the following values:

  • FAIL (default) - server rejects the content with a 409 error
  • CREATE_VERSION - server creates a new version of the existing artifact and returns it
  • FIND_OR_CREATE_VERSION - server returns an existing version that matches the provided content if such a version exists, otherwise a new version is created

This operation may fail for one of the following reasons:

  • An invalid ArtifactType was indicated (HTTP error 400)
  • No ArtifactType was indicated and the server could not determine one from the content (HTTP error 400)
  • Provided content (request body) was empty (HTTP error 400)
  • An invalid version number was used for the optional included first version (HTTP error 400)
  • An artifact with the provided ID already exists (HTTP error 409)
  • The content violates one of the configured global rules (HTTP error 409)
  • A server error occurred (HTTP error 500)

Note that if the dryRun query parameter is set to true, then this operation will not actually make any changes. Instead it will succeed or fail based on whether it would have worked. Use this option to, for example, check if an artifact is valid or if a new version passes configured compatibility checks.

path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

query Parameters
ifExists
string (IfArtifactExists)
Enum: "FAIL" "CREATE_VERSION" "FIND_OR_CREATE_VERSION"

Set this option to instruct the server on what to do if the artifact already exists.

canonical
boolean

Used only when the ifExists query parameter is set to RETURN_OR_UPDATE, this parameter can be set to true to indicate that the server should "canonicalize" the content when searching for a matching version. The canonicalization algorithm is unique to each artifact type, but typically involves removing extra whitespace and formatting the content in a consistent manner.

dryRun
boolean

When set to true, the operation will not result in any changes. Instead, it will return a result based on whether the operation would have succeeded.

Request Body schema: application/json
required

The artifact being created.

artifactId
required
string (ArtifactId) ^.{1,512}$

The ID of a single artifact.

artifactType
string (ArtifactType)
name
string
description
string
object (Labels)

User-defined name-value pairs. Name and value must be strings.

object (CreateVersion)

Responses

Request samples

Content type
application/json
{
  • "artifactId": "mytopic-value",
  • "artifactType": "AVRO",
  • "name": "Invoice",
  • "description": "A standard Acme invoice payload.",
  • "labels": {
    },
  • "firstVersion": {
    }
}

Response samples

Content type
application/json
{
  • "artifact": {
    },
  • "version": {
    }
}

Delete artifacts in group

Deletes all of the artifacts that exist in a given group.

path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
{
  • "error_code": 500,
  • "message": "Lost connection to the database."
}

List artifact references by hash

Returns a list containing all the artifact references using the artifact content hash.

This operation may fail for one of the following reasons:

  • A server error occurred (HTTP error 500)
path Parameters
contentHash
required
string

SHA-256 content hash for a single artifact content.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get artifact content by SHA-256 hash

Gets the content for an artifact version in the registry using the SHA-256 hash of the content. This content hash may be shared by multiple artifact versions in the case where the artifact versions have identical content.

This operation may fail for one of the following reasons:

  • No content with this contentHash exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
contentHash
required
string

SHA-256 content hash for a single artifact content.

Responses

Response samples

Content type
*/*
{
  "openapi": "3.0.2",
  "info": {
    "title": "Empty API",
    "version": "1.0.0",
    "description": "An example API design using OpenAPI."
  }
}

Get artifact content by ID

Gets the content for an artifact version in the registry using the unique content identifier for that content. This content ID may be shared by multiple artifact versions in the case where the artifact versions are identical.

This operation may fail for one of the following reasons:

  • No content with this contentId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
contentId
required
integer <int64>

Global identifier for a single artifact content.

Responses

Response samples

Content type
*/*
{
  "openapi": "3.0.2",
  "info": {
    "title": "Empty API",
    "version": "1.0.0",
    "description": "An example API design using OpenAPI."
  }
}

Delete artifact

Deletes an artifact completely, resulting in all versions of the artifact also being deleted. This may fail for one of the following reasons:

  • No artifact with the artifactId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Metadata

Sometimes the metadata for an artifact is important. For example, metadata includes when the artifact was created, last updated, and so on. This section contains operations to access (and in some cases change) an artifact's metadata.

Get artifact version metadata

Retrieves the metadata for a single version of the artifact. The version metadata is a subset of the artifact metadata and only includes the metadata that is specific to the version (for example, this doesn't include modifiedOn).

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Responses

Response samples

Content type
application/json
{
  • "groupId": "My-Group",
  • "artifactId": "my-artifact-id",
  • "version": 1221432,
  • "artifactType": "PROTOBUF",
  • "name": "Artifact Name",
  • "description": "The description of the artifact",
  • "owner": "user1",
  • "createdOn": "2019-05-17T12:00:00Z",
  • "globalId": 183282932983,
  • "contentId": 12347,
  • "labels": {
    }
}

Update artifact version metadata

Updates the user-editable portion of the artifact version's metadata. Only some of the metadata fields are editable by the user. For example, description is editable, but createdOn is not.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
Request Body schema: application/json
required
name
string
description
string
object (Labels)

User-defined name-value pairs. Name and value must be strings.

Responses

Request samples

Content type
application/json
{
  • "name": "Artifact Name",
  • "description": "The description of the artifact.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Get artifact metadata

Gets the metadata for an artifact in the registry, based on the latest version. If the latest version of the artifact is marked as DISABLED, the next available non-disabled version will be used. The returned metadata includes both generated (read-only) and editable metadata (such as name and description).

This operation can fail for the following reasons:

  • No artifact with this artifactId exists or all versions are DISABLED (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
{
  • "groupId": "My-Group",
  • "artifactId": "Procurement-Invoice",
  • "name": "Artifact Name",
  • "description": "Description of the artifact",
  • "artifactType": "AVRO",
  • "owner": "user1",
  • "createdOn": "2019-03-22T12:51:19Z",
  • "modifiedBy": "user2",
  • "modifiedOn": "2019-07-19T15:09:00Z",
  • "labels": {
    }
}

Update artifact metadata

Updates the editable parts of the artifact's metadata. Not all metadata fields can be updated. Note that only the properties included will be updated. You can update only the name by including only the name property in the payload of the request. Properties that are allowed but not present will result in the artifact's metadata not being changed.

This operation can fail for the following reasons:

  • No artifact with the artifactId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

Request Body schema: application/json
required

Updated artifact metadata.

name
string
description
string
object (Labels)

User-defined name-value pairs. Name and value must be strings.

owner
string

Responses

Request samples

Content type
application/json
{
  • "name": "Artifact Name",
  • "description": "The description of the artifact.",
  • "owner": "user-1",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Versions

When artifact content is updated, old versions of the artifact content are not lost. All versions can be listed and accessed if necessary. This section describes the operations used to list and access all versions of an artifact's content and metadata.

Delete artifact version

Deletes a single version of the artifact. Parameters groupId, artifactId and the unique version are needed. If this is the only version of the artifact, this operation is the same as deleting the entire artifact.

This feature is disabled by default and it's discouraged for normal usage. To enable it, set the registry.rest.artifact.deletion.enabled property to true. This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • Feature is disabled (HTTP error 405)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Responses

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Get artifact version references

Retrieves all references for a single version of an artifact. Both the artifactId and the unique version number must be provided. Using the refType query parameter, it is possible to retrieve an array of either the inbound or outbound references.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
query Parameters
refType
string (ReferenceType)
Enum: "OUTBOUND" "INBOUND"
Example: refType="INBOUND"

Determines the type of reference to return, either INBOUND or OUTBOUND. Defaults to OUTBOUND.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get artifact version comments

Retrieves all comments for a version of an artifact. Both the artifactId and the unique version number must be provided.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add new comment

Adds a new comment to the artifact version. Both the artifactId and the unique version number must be provided.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
Request Body schema: application/json
required
value
required
string

Responses

Request samples

Content type
application/json
{
  • "value": "This is a new comment on an existing artifact version."
}

Response samples

Content type
application/json
{
  • "commentId": "12345",
  • "value": "This is a comment on an artifact version.",
  • "owner": "bwayne",
  • "createdOn": "2023-07-01T15:22:01Z"
}

Update a comment

Updates the value of a single comment in an artifact version. Only the owner of the comment can modify it. The artifactId, unique version number, and commentId must be provided.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • No comment with this commentId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
commentId
required
string

The unique identifier of a single comment.

Request Body schema: application/json
required
value
required
string

Responses

Request samples

Content type
application/json
{
  • "value": "This is a new comment on an existing artifact version."
}

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Delete a single comment

Deletes a single comment in an artifact version. Only the owner of the comment can delete it. The artifactId, unique version number, and commentId must be provided.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • No comment with this commentId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
commentId
required
string

The unique identifier of a single comment.

Responses

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

List artifact versions

Returns a list of all versions of the artifact. The result set is paged.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

query Parameters
offset
integer

The number of versions to skip before starting to collect the result set. Defaults to 0.

limit
integer

The number of versions to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (VersionSortBy)
Enum: "groupId" "artifactId" "version" "name" "createdOn" "modifiedOn" "globalId"

The field to sort by. Can be one of:

  • name
  • version
  • createdOn

Responses

Response samples

Content type
application/json
[
  • 5,
  • 6,
  • 10,
  • 103
]

Create artifact version

Creates a new version of the artifact by uploading new content. The configured rules for the artifact are applied, and if they all pass, the new content is added as the most recent version of the artifact. If any of the rules fail, an error is returned.

The body of the request can be the raw content of the new artifact version, or the raw content and a set of references pointing to other artifacts, and the type of that content should match the artifact's type (for example if the artifact type is AVRO then the content of the request should be an Apache Avro document).

This operation can fail for the following reasons:

  • Provided content (request body) was empty (HTTP error 400)
  • An invalid version number was provided (HTTP error 400)
  • No artifact with this artifactId exists (HTTP error 404)
  • The new content violates one of the rules configured for the artifact (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

query Parameters
dryRun
boolean

When set to true, the operation will not result in any changes. Instead, it will return a result based on whether the operation would have succeeded.

Request Body schema: application/json
required

The version to be created.

version
string (Version) ^[a-zA-Z0-9._\-+]{1,256}$

A single version of an artifact. Can be provided by the client when creating a new version, or it can be server-generated. The value can be any string unique to the artifact, but it is recommended to use a simple integer or a semver value.

required
object (VersionContent)
name
string
description
string
object (Labels)

User-defined name-value pairs. Name and value must be strings.

branches
Array of strings
isDraft
boolean

Responses

Request samples

Content type
application/json
{
  • "version": "\"3.1.6\"",
  • "content": {
    },
  • "name": "string",
  • "description": "string",
  • "labels": {
    },
  • "branches": [
    ],
  • "isDraft": true
}

Response samples

Content type
application/json
{
  • "groupId": "My-Group",
  • "artifactId": "my-artifact-id",
  • "version": 1221432,
  • "artifactType": "PROTOBUF",
  • "name": "Artifact Name",
  • "description": "The description of the artifact",
  • "owner": "user1",
  • "createdOn": "2019-05-17T12:00:00Z",
  • "globalId": 183282932983,
  • "contentId": 12347,
  • "labels": {
    }
}

Get artifact version

Retrieves a single version of the artifact content. Both the artifactId and the unique version number must be provided. The Content-Type of the response depends on the artifact type. In most cases, this is application/json, but for some types it may be different (for example, PROTOBUF).

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
query Parameters
references
string (HandleReferencesType)
Enum: "PRESERVE" "DEREFERENCE" "REWRITE"

Allows the user to specify how references in the content should be treated.

Responses

Response samples

Content type
*/*
{
  "openapi": "3.0.2",
  "info": {
    "title": "Empty API",
    "version": "1.0.0",
    "description": "An example API design using OpenAPI."
  }
}

Update artifact version content

Updates the content of a single version of an artifact.

NOTE: the artifact must be in DRAFT status.

Both the artifactId and the unique version number must be provided to identify the version to update.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • Artifact version not in DRAFT status (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
Request Body schema: application/json
required

The new artifact version content.

content
required
string

Raw content of the artifact version or a valid (and accessible) URL where the content can be found.

Array of objects (Root Type for ArtifactReference)

Collection of references to other artifacts.

contentType
required
string

The content-type, such as application/json or text/xml.

Responses

Request samples

Content type
application/json
{
  • "content": "",
  • "references": [
    ],
  • "contentType": "string"
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Search for versions

Returns a paginated list of all versions that match the provided filter criteria.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
query Parameters
version
string (Version) ^[a-zA-Z0-9._\-+]{1,256}$
Example: version="3.1.6"

Filter by version number.

offset
integer
Default: 0

The number of versions to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of versions to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (VersionSortBy)
Enum: "groupId" "artifactId" "version" "name" "createdOn" "modifiedOn" "globalId"

The field to sort by. Can be one of:

  • name
  • createdOn
labels
Array of strings

Filter by one or more name/value label. Separate each name/value pair using a colon. For example labels=foo:bar will return only artifacts with a label named foo and value bar.

description
string

Filter by description.

groupId
string (GroupId) ^.{1,512}$
Example: groupId="my-group"

Filter by artifact group.

globalId
integer <int64>

Filter by globalId.

contentId
integer <int64>

Filter by contentId.

artifactId
string (ArtifactId) ^.{1,512}$
Example: artifactId="example-artifact"

Filter by artifactId.

name
string

Filter by name.

state
string (VersionState)
Enum: "ENABLED" "DISABLED" "DEPRECATED" "DRAFT"

Filter by version state.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Filter by artifact type (AVRO, JSON, etc).

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "versions": [
    ]
}

Search for versions by content

Returns a paginated list of all versions that match the posted content.

This operation can fail for the following reasons:

  • Provided content (request body) was empty (HTTP error 400)
  • A server error occurred (HTTP error 500)
query Parameters
canonical
boolean

Parameter that can be set to true to indicate that the server should "canonicalize" the content when searching for matching artifacts. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner. Must be used along with the artifactType query parameter.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Indicates the type of artifact represented by the content being used for the search. This is only needed when using the canonical query parameter, so that the server knows how to canonicalize the content prior to searching for matching versions.

offset
integer
Default: 0

The number of versions to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of versions to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (VersionSortBy)
Enum: "groupId" "artifactId" "version" "name" "createdOn" "modifiedOn" "globalId"

The field to sort by. Can be one of:

  • name
  • createdOn
groupId
string (GroupId) ^.{1,512}$
Example: groupId="my-group"

Filter by group Id.

artifactId
string (ArtifactId) ^.{1,512}$
Example: artifactId="example-artifact"

Filter by artifact Id.

Request Body schema: */*
required

The content to search for.

string <binary> (FileContent)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "versions": [
    ]
}

Get artifact version state

Gets the current state of an artifact version.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Responses

Response samples

Content type
application/json
{
  • "state": "ENABLED"
}

Update the artifact version state

Updates the state of an artifact version.

NOTE: There are some restrictions on state transitions. Notably a version cannot be transitioned to the DRAFT state from any other state. The DRAFT state can only be entered (optionally) when creating a new artifact/version. A version in DRAFT state can only be transitioned to ENABLED. When this happens, any configured content rules will be applied. This may result in a failure to change the state.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No version with this version exists (HTTP error 404)
  • An invalid new state was provided (HTTP error 400)
  • The draft content violates one or more of the rules configured for the artifact (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

versionExpression
required
string

An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:

  • If the expression is in the form "branch={branchId}", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.
  • Otherwise: The expression is resolved to a version with the same ID, which must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.
query Parameters
dryRun
boolean

When set to true, the operation will not result in any changes. Instead, it will return a result based on whether the operation would have succeeded.

Request Body schema: application/json
required

The new state.

state
required
string (VersionState)
Enum: "ENABLED" "DISABLED" "DEPRECATED" "DRAFT"

Describes the state of an artifact or artifact version. The following states are possible:

  • ENABLED
  • DISABLED
  • DEPRECATED

Responses

Request samples

Content type
application/json
{
  • "state": "ENABLED"
}

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Artifact rules

Rules can be configured on a per-artifact basis, allowing for different approaches to content evolution for each artifact. These rules override any global rules that have been configured. This section contains the operations used to manage a single artifact's rules.

List artifact rules

Returns a list of all rules configured for the artifact. The set of rules determines how the content of an artifact can evolve over time. If no rules are configured for an artifact, then the rules configured for the group is used. If no rules are configured at the group level, then the set of globally configured rules are used.
If no global rules are defined, there are no restrictions on content evolution.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
[
  • "VALIDITY"
]

Create artifact rule

Adds a rule to the list of rules that get applied to the artifact when adding new versions. All configured rules must pass to successfully add a new artifact version.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • Rule (named in the request body) is unknown (HTTP error 400)
  • Rule is already configured (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Delete artifact rules

Deletes all of the rules configured for the artifact. After this is done, the global rules apply to the artifact again.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Get artifact rule configuration

Returns information about a single rule configured for an artifact. This is useful when you want to know what the current configuration settings are for a specific rule.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No rule with this name/type is configured for this artifact (HTTP error 404)
  • Invalid rule type (HTTP error 400)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

ruleType
required
string
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Update artifact rule configuration

Updates the configuration of a single rule for the artifact. The configuration data is specific to each rule type, so the configuration of the COMPATIBILITY rule is in a different format from the configuration of the VALIDITY rule.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No rule with this name/type is configured for this artifact (HTTP error 404)
  • Invalid rule type (HTTP error 400)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

ruleType
required
string
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

The unique name/type of a rule.

Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Delete artifact rule

Deletes a rule from the artifact. This results in the rule no longer applying for this artifact. If this is the only rule configured for the artifact, this is the same as deleting all rules, and the globally configured rules now apply to this artifact.

This operation can fail for the following reasons:

  • No artifact with this artifactId exists (HTTP error 404)
  • No rule with this name/type is configured for this artifact (HTTP error 404)
  • Invalid rule type (HTTP error 400)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

ruleType
required
string
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Global rules

Global rules can be configured in the registry to govern how artifact content can evolve over time (as artifact content is updated). Global rules are applied whenever an artifact is added to the registry, and also whenever an artifact's content is updated (only if that artifact does not have its own specific rules configured). This section describes the operations used to manage the global rules.

List global rules

Gets a list of all the currently configured global rules (if any).

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
[
  • "VALIDITY"
]

Create global rule

Adds a rule to the list of globally configured rules.

This operation can fail for the following reasons:

  • The rule type is unknown (HTTP error 400)
  • The rule already exists (HTTP error 409)
  • A server error occurred (HTTP error 500)
Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Delete all global rules

Deletes all globally configured rules.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
{
  • "error_code": 500,
  • "message": "Lost connection to the database."
}

Get global rule configuration

Returns information about the named globally configured rule.

This operation can fail for the following reasons:

  • Invalid rule name/type (HTTP error 400)
  • No rule with name/type rule exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
ruleType
required
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"
Example: VALIDITY

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Update global rule configuration

Updates the configuration for a globally configured rule.

This operation can fail for the following reasons:

  • Invalid rule name/type (HTTP error 400)
  • No rule with name/type rule exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
ruleType
required
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"
Example: VALIDITY

The unique name/type of a rule.

Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Delete global rule

Deletes a single global rule. If this is the only rule configured, this is the same as deleting all rules.

This operation can fail for the following reasons:

  • Invalid rule name/type (HTTP error 400)
  • No rule with name/type rule exists (HTTP error 404)
  • Rule cannot be deleted (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
ruleType
required
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"
Example: VALIDITY

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Search

The search API is used to browse or find artifacts in the registry. This section describes the operations for searching for artifacts and versions.

Search for artifacts

Returns a paginated list of all artifacts that match the provided filter criteria.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
query Parameters
name
string

Filter by artifact name.

offset
integer
Default: 0

The number of artifacts to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of artifacts to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (ArtifactSortBy)
Enum: "groupId" "artifactId" "createdOn" "modifiedOn" "artifactType" "name"

The field to sort by. Can be one of:

  • name
  • createdOn
labels
Array of strings

Filter by one or more name/value label. Separate each name/value pair using a colon. For example labels=foo:bar will return only artifacts with a label named foo and value bar.

description
string

Filter by description.

groupId
string

Filter by artifact group.

globalId
integer <int64>

Filter by globalId.

contentId
integer <int64>

Filter by contentId.

artifactId
string

Filter by artifactId.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Filter by artifact type (AVRO, JSON, etc).

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "count": 0
}

Search for artifacts by content

Returns a paginated list of all artifacts with at least one version that matches the posted content.

This operation can fail for the following reasons:

  • Provided content (request body) was empty (HTTP error 400)
  • A server error occurred (HTTP error 500)
query Parameters
canonical
boolean

Parameter that can be set to true to indicate that the server should "canonicalize" the content when searching for matching artifacts. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner. Must be used along with the artifactType query parameter.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Indicates the type of artifact represented by the content being used for the search. This is only needed when using the canonical query parameter, so that the server knows how to canonicalize the content prior to searching for matching artifacts.

groupId
string

Filter by artifact group.

offset
integer
Default: 0

The number of artifacts to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of artifacts to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (ArtifactSortBy)
Enum: "groupId" "artifactId" "createdOn" "modifiedOn" "artifactType" "name"

The field to sort by. Can be one of:

  • name
  • createdOn
Request Body schema: */*
required

The content to search for.

string <binary> (FileContent)

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "count": 0
}

Search for groups

Returns a paginated list of all groups that match the provided filter criteria.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
query Parameters
offset
integer
Default: 0

The number of artifacts to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of artifacts to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (GroupSortBy)
Enum: "groupId" "createdOn" "modifiedOn"

The field to sort by. Can be one of:

  • name
  • createdOn
labels
Array of strings

Filter by one or more name/value label. Separate each name/value pair using a colon. For example labels=foo:bar will return only artifacts with a label named foo and value bar.

description
string

Filter by description.

groupId
string

Filter by group name.

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "count": 0
}

Search for versions

Returns a paginated list of all versions that match the provided filter criteria.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
query Parameters
version
string (Version) ^[a-zA-Z0-9._\-+]{1,256}$
Example: version="3.1.6"

Filter by version number.

offset
integer
Default: 0

The number of versions to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of versions to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (VersionSortBy)
Enum: "groupId" "artifactId" "version" "name" "createdOn" "modifiedOn" "globalId"

The field to sort by. Can be one of:

  • name
  • createdOn
labels
Array of strings

Filter by one or more name/value label. Separate each name/value pair using a colon. For example labels=foo:bar will return only artifacts with a label named foo and value bar.

description
string

Filter by description.

groupId
string (GroupId) ^.{1,512}$
Example: groupId="my-group"

Filter by artifact group.

globalId
integer <int64>

Filter by globalId.

contentId
integer <int64>

Filter by contentId.

artifactId
string (ArtifactId) ^.{1,512}$
Example: artifactId="example-artifact"

Filter by artifactId.

name
string

Filter by name.

state
string (VersionState)
Enum: "ENABLED" "DISABLED" "DEPRECATED" "DRAFT"

Filter by version state.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Filter by artifact type (AVRO, JSON, etc).

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "versions": [
    ]
}

Search for versions by content

Returns a paginated list of all versions that match the posted content.

This operation can fail for the following reasons:

  • Provided content (request body) was empty (HTTP error 400)
  • A server error occurred (HTTP error 500)
query Parameters
canonical
boolean

Parameter that can be set to true to indicate that the server should "canonicalize" the content when searching for matching artifacts. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner. Must be used along with the artifactType query parameter.

artifactType
string (ArtifactType)
Example: artifactType=AVRO

Indicates the type of artifact represented by the content being used for the search. This is only needed when using the canonical query parameter, so that the server knows how to canonicalize the content prior to searching for matching versions.

offset
integer
Default: 0

The number of versions to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of versions to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (VersionSortBy)
Enum: "groupId" "artifactId" "version" "name" "createdOn" "modifiedOn" "globalId"

The field to sort by. Can be one of:

  • name
  • createdOn
groupId
string (GroupId) ^.{1,512}$
Example: groupId="my-group"

Filter by group Id.

artifactId
string (ArtifactId) ^.{1,512}$
Example: artifactId="example-artifact"

Filter by artifact Id.

Request Body schema: */*
required

The content to search for.

string <binary> (FileContent)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "versions": [
    ]
}

Admin

Application functionality that is only accessible to admin users. Includes logging, global rules, and export/import of registry data.

List global rules

Gets a list of all the currently configured global rules (if any).

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
[
  • "VALIDITY"
]

Create global rule

Adds a rule to the list of globally configured rules.

This operation can fail for the following reasons:

  • The rule type is unknown (HTTP error 400)
  • The rule already exists (HTTP error 409)
  • A server error occurred (HTTP error 500)
Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Delete all global rules

Deletes all globally configured rules.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
{
  • "error_code": 500,
  • "message": "Lost connection to the database."
}

Get global rule configuration

Returns information about the named globally configured rule.

This operation can fail for the following reasons:

  • Invalid rule name/type (HTTP error 400)
  • No rule with name/type rule exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
ruleType
required
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"
Example: VALIDITY

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Update global rule configuration

Updates the configuration for a globally configured rule.

This operation can fail for the following reasons:

  • Invalid rule name/type (HTTP error 400)
  • No rule with name/type rule exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
ruleType
required
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"
Example: VALIDITY

The unique name/type of a rule.

Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Delete global rule

Deletes a single global rule. If this is the only rule configured, this is the same as deleting all rules.

This operation can fail for the following reasons:

  • Invalid rule name/type (HTTP error 400)
  • No rule with name/type rule exists (HTTP error 404)
  • Rule cannot be deleted (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
ruleType
required
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"
Example: VALIDITY

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Export registry data

Exports registry data as a ZIP archive.

query Parameters
forBrowser
boolean

Indicates if the operation is done for a browser. If true, the response will be a JSON payload with a property called href. This href will be a single-use, naked download link suitable for use by a web browser to download the content.

Responses

Response samples

Content type
No sample

Import registry data

Imports registry data that was previously exported using the /admin/export operation.

query Parameters
requireEmptyRegistry
boolean

Query parameter indicating whether the registry must be empty before allowing data to be imported. Defaults to true if omitted.

header Parameters
X-Registry-Preserve-GlobalId
boolean

If this header is set to false, global ids of imported data will be ignored and replaced by next id in global id sequence. This allows to import any data even thought the global ids would cause a conflict.

X-Registry-Preserve-ContentId
boolean

If this header is set to false, content ids of imported data will be ignored and replaced by next id in content id sequence. The mapping between content and artifacts will be preserved. This allows to import any data even thought the content ids would cause a conflict.

Request Body schema: application/zip
required

The ZIP file representing the previously exported registry data.

string <binary> (FileContent)

Responses

Response samples

Content type
application/json
{
  • "error_code": 409,
  • "message": "The artifact content was invalid."
}

Return a single role mapping

Gets the details of a single role mapping (by principalId).

This operation can fail for the following reasons:

  • No role mapping for the principalId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
principalId
required
string

Unique id of a principal (typically either a user or service account).

Responses

Response samples

Content type
application/json
{
  • "principalId": "svc_account_84874587_123484",
  • "principalName": "famartin-svc-account",
  • "role": "READ_ONLY"
}

Update a role mapping

Updates a single role mapping for one user/principal.

This operation can fail for the following reasons:

  • No role mapping for the principalId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
principalId
required
string

Unique id of a principal (typically either a user or service account).

Request Body schema: application/json
required
role
required
string (RoleType)
Enum: "READ_ONLY" "DEVELOPER" "ADMIN"

Responses

Request samples

Content type
application/json
{
  • "role": "READ_ONLY"
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Delete a role mapping

Deletes a single role mapping, effectively denying access to a user/principal.

This operation can fail for the following reasons:

  • No role mapping for the principalId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
principalId
required
string

Unique id of a principal (typically either a user or service account).

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

List all configuration properties

Returns a list of all configuration properties that have been set. The list is not paged.

This operation may fail for one of the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get configuration property value

Returns the value of a single configuration property.

This operation may fail for one of the following reasons:

  • Property not found or not configured (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
propertyName
required
string

The name of a configuration property.

Responses

Response samples

Content type
application/json
{
  • "name": "registry.auth.owner-only-authorization",
  • "value": "true",
  • "type": "boolean",
  • "label": "Owner Only Authorization",
  • "description": "When enabled, the registry will allow only the artifact owner (creator) to modify an artifact."
}

Update a configuration property

Updates the value of a single configuration property.

This operation may fail for one of the following reasons:

  • Property not found or not configured (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
propertyName
required
string

The name of a configuration property.

Request Body schema: application/json
required
value
required
string

Responses

Request samples

Content type
application/json
{
  • "value": "true"
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Reset a configuration property

Resets the value of a single configuration property. This will return the property to its default value (see external documentation for supported properties and their default values).

This operation may fail for one of the following reasons:

  • Property not found or not configured (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
propertyName
required
string

The name of a configuration property.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

List all role mappings

Gets a list of all role mappings configured in the registry (if any).

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
query Parameters
limit
integer

The number of role mappings to return. Defaults to 20.

offset
integer

The number of role mappings to skip before starting the result set. Defaults to 0.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a new role mapping

Creates a new mapping between a user/principal and a role.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
Request Body schema: application/json
required
principalId
required
string
role
required
string (RoleType)
Enum: "READ_ONLY" "DEVELOPER" "ADMIN"
principalName
string

A friendly name for the principal.

Responses

Request samples

Content type
application/json
{
  • "principalId": "svc_account_84874587_123484",
  • "principalName": "famartin-svc-account",
  • "role": "READ_ONLY"
}

Response samples

Content type
application/json
{
  • "error_code": 500,
  • "message": "Lost connection to the database."
}

List artifact types

Gets a list of all the configured artifact types.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Trigger storage snapshot

Triggers the creation of a snapshot of the internal database for compatible storages.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
{
  • "snapshotId": "snp-1137292771"
}

System

System level functionality, including versioning and status information.

Get system information

This operation retrieves information about the running registry system, such as the version of the software and when it was built.

Responses

Response samples

Content type
application/json
{
  • "name": "Solace Schema Registry",
  • "description": "The Solace Schema Registry application.",
  • "version": "1.0.0",
  • "builtOn": "2025-07-14T12:55:00Z"
}

Get resource limits information

This operation retrieves the list of limitations on used resources, that are applied on the current instance of Registry.

Responses

Response samples

Content type
application/json
{
  • "maxTotalSchemasCount": -1,
  • "maxSchemaSizeBytes": -1,
  • "maxArtifactsCount": -1,
  • "maxVersionsPerArtifactCount": -1,
  • "maxArtifactPropertiesCount": -1,
  • "maxPropertyKeySizeBytes": -1,
  • "maxPropertyValueSizeBytes": -1,
  • "maxArtifactLabelsCount": -1,
  • "maxLabelSizeBytes": -1,
  • "maxArtifactNameLengthChars": -1,
  • "maxArtifactDescriptionLengthChars": -1,
  • "maxRequestsPerSecondCount": -1
}

Get UI config

Returns the UI configuration properties for this server. The registry UI can be connected to a backend using just a URL. The rest of the UI configuration can then be fetched from the backend using this operation. This allows UI and backend to both be configured in the same place.

This operation may fail for one of the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
{
  • "ui": {},
  • "auth": {
    },
  • "features": {
    }
}

Users

Operations related to users.

Get current user

Returns information about the currently authenticated user.

Responses

Response samples

Content type
application/json
{
  • "username": "dprince",
  • "displayName": "Diana Prince",
  • "admin": true,
  • "developer": false,
  • "viewer": false
}

Groups

Registry artifacts can be collected together using groups. This section includes all of the primary operations related to groups.

List groups

Returns a list of all groups. This list is paged.

query Parameters
limit
integer

The number of groups to return. Defaults to 20.

offset
integer

The number of groups to skip before starting the result set. Defaults to 0.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (GroupSortBy)
Enum: "groupId" "createdOn" "modifiedOn"

The field to sort by. Can be one of:

  • name
  • createdOn

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "count": 0
}

Create a new group

Creates a new group.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
  • The group already exist (HTTP error 409)
Request Body schema: application/json
required
description
string
object (Labels)

User-defined name-value pairs. Name and value must be strings.

groupId
required
string (GroupId) ^.{1,512}$

An ID of a single artifact group.

Responses

Request samples

Content type
application/json
{
  • "groupId": "group-identifier",
  • "description": "The description of the artifact.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "groupId": "group-identifier",
  • "description": "Description of the group",
  • "artifactsType": "AVRO",
  • "owner": "user1",
  • "createdOn": "2019-03-22T12:51:19Z",
  • "modifiedBy": "user2",
  • "modifiedOn": "2019-07-19T15:09:00Z",
  • "properties": {
    }
}

Get a group by the specified ID.

Returns a group using the specified id.

This operation can fail for the following reasons:

  • No group exists with the specified ID (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
{
  • "groupId": "group-identifier",
  • "description": "Description of the group",
  • "artifactsType": "AVRO",
  • "owner": "user1",
  • "createdOn": "2019-03-22T12:51:19Z",
  • "modifiedBy": "user2",
  • "modifiedOn": "2019-07-19T15:09:00Z",
  • "properties": {
    }
}

Update group metadata

Updates the metadata of a group using the specified id.

This operation can fail for the following reasons:

  • No group exists with the specified ID (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

Request Body schema: application/json
required

The new group metadata.

description
string
object (Labels)

User-defined name-value pairs. Name and value must be strings.

Responses

Request samples

Content type
application/json
{
  • "description": "The description of the group.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Delete a group by the specified ID.

Deletes a group by identifier. This operation also deletes all artifacts within the group, so should be used very carefully.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
  • The group does not exist (HTTP error 404)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Search for groups

Returns a paginated list of all groups that match the provided filter criteria.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)
query Parameters
offset
integer
Default: 0

The number of artifacts to skip before starting to collect the result set. Defaults to 0.

limit
integer
Default: 20

The number of artifacts to return. Defaults to 20.

order
string (SortOrder)
Enum: "asc" "desc"

Sort order, ascending (asc) or descending (desc).

orderby
string (GroupSortBy)
Enum: "groupId" "createdOn" "modifiedOn"

The field to sort by. Can be one of:

  • name
  • createdOn
labels
Array of strings

Filter by one or more name/value label. Separate each name/value pair using a colon. For example labels=foo:bar will return only artifacts with a label named foo and value bar.

description
string

Filter by description.

groupId
string

Filter by group name.

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "count": 0
}

Branches

Artifacts can optionally have branches that are just an ordered list of version identifiers.

List branches

Returns a list of all branches in the artifact. Each branch is a list of version identifiers, ordered from the latest (tip of the branch) to the oldest.

This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

query Parameters
offset
integer

The number of branches to skip before starting to collect the result set. Defaults to 0.

limit
integer

The number of branches to return. Defaults to 20.

Responses

Response samples

Content type
application/json
{
  • "branches": [
    ],
  • "count": 0
}

Create a new branch

Creates a new branch for the artifact. A new branch consists of metadata and a list of versions.

This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • A branch with the given branchId already exists (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

Request Body schema: application/json
required
description
string
branchId
required
string (BranchId) ^[a-zA-Z0-9._\-+]{1,256}$

The ID of a single artifact branch.

versions
Array of strings (Version) [ items^[a-zA-Z0-9._\-+]{1,256}$ ]

Responses

Request samples

Content type
application/json
{
  • "branchId": "1.0.x",
  • "description": "The description of the branch."
}

Response samples

Content type
application/json
{
  • "groupId": "ExampleGroup",
  • "artifactId": "ExampleArtifact",
  • "branchId": "1.0.x",
  • "description": "Just an example branch.",
  • "systemDefined": false,
  • "createdOn": "2018-02-10T09:30Z",
  • "modifiedBy": "user1",
  • "modifiedOn": "2020-02-10T09:30Z",
  • "owner": "user2"
}

Get branch metaData

Returns the metaData of a branch.

This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • No branch with this branchId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

branchId
required
string (BranchId) ^[a-zA-Z0-9._\-+]{1,256}$
Example: "latest"

Artifact branch ID. Must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Responses

Response samples

Content type
application/json
{
  • "groupId": "ExampleGroup",
  • "artifactId": "ExampleArtifact",
  • "branchId": "1.0.x",
  • "description": "Just an example branch.",
  • "systemDefined": false,
  • "createdOn": "2018-02-10T09:30Z",
  • "modifiedBy": "user1",
  • "modifiedOn": "2020-02-10T09:30Z",
  • "owner": "user2"
}

Update branch metaData

Updates the metadata of a branch.

This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • No branch with this branchId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

branchId
required
string (BranchId) ^[a-zA-Z0-9._\-+]{1,256}$
Example: "latest"

Artifact branch ID. Must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Request Body schema: application/json
required
description
string

Responses

Request samples

Content type
application/json
{
  • "description": "The description of the group."
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Delete branch.

Deletes a single branch in the artifact.

This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • No branch with this branchId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

branchId
required
string (BranchId) ^[a-zA-Z0-9._\-+]{1,256}$
Example: "latest"

Artifact branch ID. Must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Get versions in branch

Get a list of all versions in the branch. Returns a list of version identifiers in the branch, ordered from the latest (tip of the branch) to the oldest.

This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • No branch with this branchId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

branchId
required
string (BranchId) ^[a-zA-Z0-9._\-+]{1,256}$
Example: "latest"

Artifact branch ID. Must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

query Parameters
offset
integer

The number of versions to skip before starting to collect the result set. Defaults to 0.

limit
integer

The number of versions to return. Defaults to 20.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "versions": [
    ]
}

Replace list of versions in branch

Add a new version to an artifact branch. Branch is created if it does not exist. Returns a list of version identifiers in the artifact branch, ordered from the latest (tip of the branch) to the oldest. This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • No branch with this branchId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

branchId
required
string (BranchId) ^[a-zA-Z0-9._\-+]{1,256}$
Example: "latest"

Artifact branch ID. Must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Request Body schema: application/json
required

A new list of versions that should be on the branch.

versions
required
Array of strings (Version) [ items^[a-zA-Z0-9._\-+]{1,256}$ ]

Responses

Request samples

Content type
application/json
{
  • "versions": [
    ]
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Add a new version to a branch.

Add a new version to an artifact branch. Returns a list of version identifiers in the branch, ordered from the latest (tip of the branch) to the oldest.

This operation can fail for the following reasons:

  • No artifact with this groupId and artifactId exists (HTTP error 404)
  • No branch with this branchId exists (HTTP error 404)
  • Branch already contains the given version. Artifact branches are append-only, cycles and history rewrites, except by replacing the entire branch using the replaceBranchVersions operation, are not supported. (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

artifactId
required
string (ArtifactId) ^.{1,512}$
Example: "example-artifact"

The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.

branchId
required
string (BranchId) ^[a-zA-Z0-9._\-+]{1,256}$
Example: "latest"

Artifact branch ID. Must follow the "[a-zA-Z0-9._\-+]{1,256}" pattern.

Request Body schema: application/json
required

The version to add to the branch.

version
required
string

Responses

Request samples

Content type
application/json
{
  • "version": "string"
}

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Group rules

Rules can be configured on a per-group basis, allowing for different approaches to content evolution for artifacts in the group. These rules override any global rules that have been configured. This section contains the operations used to manage the rules in a single group.

List group rules

Returns a list of all rules configured for the group. The set of rules determines how the content of an artifact in the group can evolve over time. If no rules are configured for a group, the set of globally configured rules are used.

This operation can fail for the following reasons:

  • No group with this groupId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
[
  • "VALIDITY"
]

Create group rule

Adds a rule to the list of rules that get applied to an artifact in the group when adding new versions. All configured rules must pass to successfully add a new artifact version.

This operation can fail for the following reasons:

  • No group with this groupId exists (HTTP error 404)
  • Rule (named in the request body) is unknown (HTTP error 400)
  • Rule is already configured (HTTP error 409)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "status": 500,
  • "name": "NullPointerException",
  • "title": "An error occurred somewhere."
}

Delete group rules

Deletes all of the rules configured for the group. After this is done, the global rules apply to artifacts in the group again.

This operation can fail for the following reasons:

  • No group with this groupId exists (HTTP error 404)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Get group rule configuration

Returns information about a single rule configured for a group. This is useful when you want to know what the current configuration settings are for a specific rule.

This operation can fail for the following reasons:

  • No group with this groupId exists (HTTP error 404)
  • No rule with this name/type is configured for this artifact (HTTP error 404)
  • Invalid rule type (HTTP error 400)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

ruleType
required
string
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Update group rule configuration

Updates the configuration of a single rule for the group. The configuration data is specific to each rule type, so the configuration of the COMPATIBILITY rule is in a different format from the configuration of the VALIDITY rule.

This operation can fail for the following reasons:

  • No group with this groupId exists (HTTP error 404)
  • No rule with this name/type is configured for this artifact (HTTP error 404)
  • Invalid rule type (HTTP error 400)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

ruleType
required
string
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

The unique name/type of a rule.

Request Body schema: application/json
required
config
required
string
ruleType
string (RuleType)
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

Responses

Request samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Response samples

Content type
application/json
{
  • "ruleType": "VALIDITY",
  • "config": "FULL"
}

Delete group rule

Deletes a rule from the group. This results in the rule no longer applying for this group. If this is the only rule configured for the group, this is the same as deleting all rules, and the globally configured rules now apply to this group.

This operation can fail for the following reasons:

  • No group with this groupId exists (HTTP error 404)
  • No rule with this name/type is configured for this group (HTTP error 404)
  • Invalid rule type (HTTP error 400)
  • A server error occurred (HTTP error 500)
path Parameters
groupId
required
string (GroupId) ^.{1,512}$
Example: "my-group"

The group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.

ruleType
required
string
Enum: "VALIDITY" "COMPATIBILITY" "INTEGRITY"

The unique name/type of a rule.

Responses

Response samples

Content type
application/json
{
  • "error_code": 404,
  • "message": "No artifact with id 'Topic-1/Inbound' could be found."
}

Artifact Type

List artifact types

Gets a list of all the configured artifact types.

This operation can fail for the following reasons:

  • A server error occurred (HTTP error 500)

Responses

Response samples

Content type
application/json
[
  • {
    }
]