Sign in

v1

latestOpenAPI 3.0.2Apache 2.02026-07-136548173.9 KB
Artifacts

Create artifact

Creates a new artifact by posting the artifact content. The body of the request should be the raw content of the artifact. This is typically in JSON format for most of the supported types, but may be in another format for a few (for example, PROTOBUF).

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)
  • Kafka Connect (KCONNECT)
  • OpenAPI (OPENAPI)
  • AsyncAPI (ASYNCAPI)
  • GraphQL (GRAPHQL)
  • Web Services Description Language (WSDL)
  • XML Schema (XSD)

Alternatively, you can specify the artifact type using the X-Registry-ArtifactType HTTP request header, or include a hint in the request's Content-Type. For example:

Content-Type: application/json; artifactType=AVRO

An artifact is created using the content provided in the body of the request. This content is created under a unique artifact ID that can be provided in the request using the X-Registry-ArtifactId request header. If not provided in the request, the server generates a unique ID for the artifact. It is typically recommended that callers provide the ID, because this is typically a meaningful identifier, and 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
  • UPDATE - server updates the existing artifact and returns the new metadata
  • RETURN - server does not create or add content to the server, but instead returns the metadata for the existing artifact
  • RETURN_OR_UPDATE - 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 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)
post/groups/{groupId}/artifacts

Query parameters

ifExists'FAIL' | 'UPDATE' | 'RETURN' | 'RETURN_OR_UPDATE'

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

canonicalboolean

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.

Headers

X-Registry-ArtifactTypestring
Example:AVRO

Specifies the type of the artifact being added. Possible values include:

  • Avro (AVRO)
  • Protobuf (PROTOBUF)
  • JSON Schema (JSON)
  • Kafka Connect (KCONNECT)
  • OpenAPI (OPENAPI)
  • AsyncAPI (ASYNCAPI)
  • GraphQL (GRAPHQL)
  • Web Services Description Language (WSDL)
  • XML Schema (XSD)
X-Registry-ArtifactIdstring

A client-provided, globally unique identifier for the new artifact.

X-Registry-Versionstring

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.

Example:"3.1.6"

Specifies the version number of this initial version of the artifact content. This would typically be a simple integer or a SemVer value. If not provided, the server will assign a version number automatically (starting with version 1).

X-Registry-Descriptionstring

Description of the artifact.

Example:"Artifact description"

Specifies the description of artifact being added. Description must be ASCII-only string. If this is not provided, the server will extract the description from the artifact content.

X-Registry-Description-Encodedstring

Base64 encoded description of the artifact.

Example:"QXJ0aWZhY3QgZGVzY3JpcHRpb24K"

Specifies the description of artifact being added. Value of this must be Base64 encoded string. If this is not provided, the server will extract the description from the artifact content.

X-Registry-Namestring

Name of the artifact.

Example:"Artifact name"

Specifies the name of artifact being added. Name must be ASCII-only string. If this is not provided, the server will extract the name from the artifact content.

X-Registry-Name-Encodedstring

Base64 encoded name of the artifact.

Example:"QXJ0aWZhY3QgbmFtZQo="

Specifies the name of artifact being added. Value of this must be Base64 encoded string. If this is not provided, the server will extract the name from the artifact content.

X-Registry-Content-Hashstring

Specifies the (optional) hash of the artifact to be verified.

X-Registry-Hash-Algorithm'SHA256' | 'MD5'

The algorithm to use when checking the content validity. (available: SHA256, MD5; default: SHA256)

Response

Artifact was successfully created.

namestring
descriptionstring
createdBystring required
createdOnstring date-time required
modifiedBystring required
modifiedOnstring date-time required
idstring required

The ID of a single artifact.

versionstring required
typestring required
globalIdinteger required
state'ENABLED' | 'DISABLED' | 'DEPRECATED' required

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

  • ENABLED
  • DISABLED
  • DEPRECATED
labelsstring[]
propertiesProperties

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

groupIdstring

An ID of a single artifact group.

contentIdinteger required

Example response

{
  "groupId": "My-Group",
  "id": "Procurement-Invoice",
  "name": "Artifact Name",
  "description": "Description of the artifact",
  "type": "AVRO",
  "version": 18,
  "createdBy": "user1",
  "createdOn": "2019-03-22T12:51:19Z",
  "modifiedBy": "user2",
  "modifiedOn": "2019-07-19T15:09:00Z",
  "globalId": 12984719247,
  "contentId": 82736,
  "labels": [
    "label-1",
    "label-2"
  ],
  "properties": {
    "custom-1": "foo",
    "custom-2": "bar"
  },
  "references": [
    {
      "groupId": "mygroup",
      "artifactId": "13842090-2ce3-11ec-8d3d-0242ac130003",
      "version": 2,
      "name": "foo.bar.Open"
    }
  ]
}