Create artifact

v1.0.0

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:

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)

Input

{
  "type": "object",
  "properties": {
    "X-Registry-ArtifactId": {
      "type": "string"
    },
    "X-Registry-ArtifactType": {
      "type": "string"
    },
    "X-Registry-Content-Hash": {
      "type": "string"
    },
    "X-Registry-Description": {
      "type": "string",
      "description": "Description of the artifact."
    },
    "X-Registry-Description-Encoded": {
      "type": "string",
      "description": "Base64 encoded description of the artifact."
    },
    "X-Registry-Hash-Algorithm": {
      "type": "string",
      "enum": [
        "SHA256",
        "MD5"
      ]
    },
    "X-Registry-Name": {
      "type": "string",
      "description": "Name of the artifact."
    },
    "X-Registry-Name-Encoded": {
      "type": "string",
      "description": "Base64 encoded name of the artifact."
    },
    "X-Registry-Version": {
      "type": "string",
      "description": "A single version of an artifact.  Can be provided by the client when creating a new version,\nor it can be server-generated.  The value can be any string unique to the artifact, but it is\nrecommended to use a simple integer or a semver value."
    },
    "canonical": {
      "type": "boolean"
    },
    "ifExists": {
      "type": "string",
      "enum": [
        "FAIL",
        "UPDATE",
        "RETURN",
        "RETURN_OR_UPDATE"
      ]
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "required": [
    "contentId",
    "createdBy",
    "createdOn",
    "globalId",
    "group",
    "id",
    "modifiedBy",
    "modifiedOn",
    "state",
    "type",
    "version"
  ],
  "properties": {
    "contentId": {
      "type": "integer",
      "format": "int64"
    },
    "createdBy": {
      "type": "string"
    },
    "createdOn": {
      "type": "string",
      "format": "date-time"
    },
    "description": {
      "type": "string"
    },
    "globalId": {
      "type": "integer",
      "format": "int64"
    },
    "groupId": {
      "type": "string",
      "description": "An ID of a single artifact group."
    },
    "id": {
      "type": "string"
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "modifiedBy": {
      "type": "string"
    },
    "modifiedOn": {
      "type": "string",
      "format": "date-time"
    },
    "name": {
      "type": "string"
    },
    "properties": {
      "type": "object"
    },
    "references": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A reference to a different artifact. Typically used with artifact types that can have dependencies like Protobuf.",
        "required": [
          "artifactId",
          "groupId",
          "name"
        ],
        "properties": {
          "artifactId": {
            "type": "string"
          },
          "groupId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        }
      }
    },
    "state": {
      "type": "string",
      "enum": [
        "ENABLED",
        "DISABLED",
        "DEPRECATED"
      ]
    },
    "type": {
      "type": "string"
    },
    "version": {
      "type": "string"
    }
  }
}