io.apicurio.registry.rest.v3.GroupsResource Maven / Gradle / Ivy
package io.apicurio.registry.rest.v3;
import io.apicurio.registry.rest.v3.beans.AddVersionToBranch;
import io.apicurio.registry.rest.v3.beans.ArtifactMetaData;
import io.apicurio.registry.rest.v3.beans.ArtifactReference;
import io.apicurio.registry.rest.v3.beans.ArtifactSearchResults;
import io.apicurio.registry.rest.v3.beans.ArtifactSortBy;
import io.apicurio.registry.rest.v3.beans.BranchMetaData;
import io.apicurio.registry.rest.v3.beans.BranchSearchResults;
import io.apicurio.registry.rest.v3.beans.Comment;
import io.apicurio.registry.rest.v3.beans.CreateArtifact;
import io.apicurio.registry.rest.v3.beans.CreateArtifactResponse;
import io.apicurio.registry.rest.v3.beans.CreateBranch;
import io.apicurio.registry.rest.v3.beans.CreateGroup;
import io.apicurio.registry.rest.v3.beans.CreateRule;
import io.apicurio.registry.rest.v3.beans.CreateVersion;
import io.apicurio.registry.rest.v3.beans.EditableArtifactMetaData;
import io.apicurio.registry.rest.v3.beans.EditableBranchMetaData;
import io.apicurio.registry.rest.v3.beans.EditableGroupMetaData;
import io.apicurio.registry.rest.v3.beans.EditableVersionMetaData;
import io.apicurio.registry.rest.v3.beans.GroupMetaData;
import io.apicurio.registry.rest.v3.beans.GroupSearchResults;
import io.apicurio.registry.rest.v3.beans.GroupSortBy;
import io.apicurio.registry.rest.v3.beans.HandleReferencesType;
import io.apicurio.registry.rest.v3.beans.IfArtifactExists;
import io.apicurio.registry.rest.v3.beans.NewComment;
import io.apicurio.registry.rest.v3.beans.ReplaceBranchVersions;
import io.apicurio.registry.rest.v3.beans.Rule;
import io.apicurio.registry.rest.v3.beans.SortOrder;
import io.apicurio.registry.rest.v3.beans.VersionContent;
import io.apicurio.registry.rest.v3.beans.VersionMetaData;
import io.apicurio.registry.rest.v3.beans.VersionSearchResults;
import io.apicurio.registry.rest.v3.beans.VersionSortBy;
import io.apicurio.registry.rest.v3.beans.WrappedVersionState;
import io.apicurio.registry.types.ReferenceType;
import io.apicurio.registry.types.RuleType;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.Response;
import java.math.BigInteger;
import java.util.List;
/**
* A JAX-RS interface. An implementation of this interface must be provided.
*/
@Path("/apis/registry/v3/groups")
public interface GroupsResource {
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}")
@GET
@Produces("application/json")
VersionMetaData getArtifactVersionMetaData(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}")
@PUT
@Consumes("application/json")
void updateArtifactVersionMetaData(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression, @NotNull EditableVersionMetaData data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}")
@DELETE
void deleteArtifactVersion(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/rules")
@GET
@Produces("application/json")
List listArtifactRules(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/rules")
@POST
@Consumes("application/json")
void createArtifactRule(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId, @NotNull CreateRule data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/rules")
@DELETE
void deleteArtifactRules(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/rules/{ruleType}")
@GET
@Produces("application/json")
Rule getArtifactRuleConfig(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("ruleType") RuleType ruleType);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/rules/{ruleType}")
@PUT
@Produces("application/json")
@Consumes("application/json")
Rule updateArtifactRuleConfig(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("ruleType") RuleType ruleType, @NotNull Rule data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/rules/{ruleType}")
@DELETE
void deleteArtifactRule(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("ruleType") RuleType ruleType);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/references")
@GET
@Produces("application/json")
List getArtifactVersionReferences(
@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression, @QueryParam("refType") ReferenceType refType);
/**
*
* Returns a list of all artifacts in the group. This list is paged.
*
*
*/
@Path("/{groupId}/artifacts")
@GET
@Produces("application/json")
ArtifactSearchResults listArtifactsInGroup(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@QueryParam("limit") BigInteger limit, @QueryParam("offset") BigInteger offset,
@QueryParam("order") SortOrder order, @QueryParam("orderby") ArtifactSortBy orderby);
/**
*
* 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)
* - Kafka Connect (
KCONNECT)
* - OpenAPI (
OPENAPI)
* - AsyncAPI (
ASYNCAPI)
* - GraphQL (
GRAPHQL)
* - Web Services Description Language (
WSDL)
* - 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 errorCREATE_VERSION - server creates a new version of the
* existing artifact and returns itFIND_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("/{groupId}/artifacts")
@POST
@Produces("application/json")
@Consumes("application/json")
CreateArtifactResponse createArtifact(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@QueryParam("ifExists") IfArtifactExists ifExists, @QueryParam("canonical") Boolean canonical,
@QueryParam("dryRun") Boolean dryRun, @NotNull CreateArtifact data);
/**
*
* Deletes all of the artifacts that exist in a given group.
*
*
*/
@Path("/{groupId}/artifacts")
@DELETE
void deleteArtifactsInGroup(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId);
/**
*
* Returns a list of all groups. This list is paged.
*
*
*/
@GET
@Produces("application/json")
GroupSearchResults listGroups(@QueryParam("limit") BigInteger limit, @QueryParam("offset") BigInteger offset,
@QueryParam("order") SortOrder order, @QueryParam("orderby") GroupSortBy orderby);
/**
*
* 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)
*
*
*/
@POST
@Produces("application/json")
@Consumes("application/json")
GroupMetaData createGroup(@NotNull CreateGroup data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments")
@GET
@Produces("application/json")
List getArtifactVersionComments(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments")
@POST
@Produces("application/json")
@Consumes("application/json")
Comment addArtifactVersionComment(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression, @NotNull NewComment data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments/{commentId}")
@PUT
@Consumes("application/json")
void updateArtifactVersionComment(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression, @PathParam("commentId") String commentId,
@NotNull NewComment data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments/{commentId}")
@DELETE
void deleteArtifactVersionComment(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression, @PathParam("commentId") String commentId);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches")
@GET
@Produces("application/json")
BranchSearchResults listBranches(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@QueryParam("offset") BigInteger offset, @QueryParam("limit") BigInteger limit);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches")
@POST
@Produces("application/json")
@Consumes("application/json")
BranchMetaData createBranch(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId, @NotNull CreateBranch data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions")
@GET
@Produces("application/json")
VersionSearchResults listArtifactVersions(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@QueryParam("offset") BigInteger offset, @QueryParam("limit") BigInteger limit,
@QueryParam("order") SortOrder order, @QueryParam("orderby") VersionSortBy orderby);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions")
@POST
@Produces("application/json")
@Consumes("application/json")
VersionMetaData createArtifactVersion(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId, @QueryParam("dryRun") Boolean dryRun,
@NotNull CreateVersion data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches/{branchId}")
@GET
@Produces("application/json")
BranchMetaData getBranchMetaData(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("branchId") @Pattern(regexp = "^[a-zA-Z0-9._\\-+]{1,256}$") String branchId);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches/{branchId}")
@PUT
@Consumes("application/json")
void updateBranchMetaData(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("branchId") @Pattern(regexp = "^[a-zA-Z0-9._\\-+]{1,256}$") String branchId,
@NotNull EditableBranchMetaData data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches/{branchId}")
@DELETE
void deleteBranch(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("branchId") @Pattern(regexp = "^[a-zA-Z0-9._\\-+]{1,256}$") String branchId);
/**
*
* 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("/{groupId}")
@GET
@Produces("application/json")
GroupMetaData getGroupById(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId);
/**
*
* 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("/{groupId}")
@PUT
@Consumes("application/json")
void updateGroupById(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@NotNull EditableGroupMetaData data);
/**
*
* 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("/{groupId}")
@DELETE
void deleteGroupById(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId);
/**
*
* 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("/{groupId}/artifacts/{artifactId}")
@GET
@Produces("application/json")
ArtifactMetaData getArtifactMetaData(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId);
/**
*
* 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("/{groupId}/artifacts/{artifactId}")
@PUT
@Consumes("application/json")
void updateArtifactMetaData(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@NotNull EditableArtifactMetaData data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}")
@DELETE
void deleteArtifact(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/content")
@GET
@Produces("*/*")
Response getArtifactVersionContent(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression,
@QueryParam("references") HandleReferencesType references);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/content")
@PUT
@Consumes("application/json")
void updateArtifactVersionContent(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression, @NotNull VersionContent data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches/{branchId}/versions")
@GET
@Produces("application/json")
VersionSearchResults listBranchVersions(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("branchId") @Pattern(regexp = "^[a-zA-Z0-9._\\-+]{1,256}$") String branchId,
@QueryParam("offset") BigInteger offset, @QueryParam("limit") BigInteger limit);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches/{branchId}/versions")
@PUT
@Consumes("application/json")
void replaceBranchVersions(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("branchId") @Pattern(regexp = "^[a-zA-Z0-9._\\-+]{1,256}$") String branchId,
@NotNull ReplaceBranchVersions data);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/branches/{branchId}/versions")
@POST
@Consumes("application/json")
void addVersionToBranch(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("branchId") @Pattern(regexp = "^[a-zA-Z0-9._\\-+]{1,256}$") String branchId,
@NotNull AddVersionToBranch data);
/**
*
* 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("/{groupId}/rules")
@GET
@Produces("application/json")
List listGroupRules(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId);
/**
*
* 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("/{groupId}/rules")
@POST
@Consumes("application/json")
void createGroupRule(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId, @NotNull CreateRule data);
/**
*
* 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("/{groupId}/rules")
@DELETE
void deleteGroupRules(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId);
/**
*
* 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("/{groupId}/rules/{ruleType}")
@GET
@Produces("application/json")
Rule getGroupRuleConfig(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("ruleType") RuleType ruleType);
/**
*
* 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("/{groupId}/rules/{ruleType}")
@PUT
@Produces("application/json")
@Consumes("application/json")
Rule updateGroupRuleConfig(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("ruleType") RuleType ruleType, @NotNull Rule data);
/**
*
* 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("/{groupId}/rules/{ruleType}")
@DELETE
void deleteGroupRule(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("ruleType") RuleType ruleType);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/state")
@GET
@Produces("application/json")
WrappedVersionState getArtifactVersionState(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression);
/**
*
* 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("/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/state")
@PUT
@Consumes("application/json")
void updateArtifactVersionState(@PathParam("groupId") @Pattern(regexp = "^.{1,512}$") String groupId,
@PathParam("artifactId") @Pattern(regexp = "^.{1,512}$") String artifactId,
@PathParam("versionExpression") String versionExpression, @QueryParam("dryRun") Boolean dryRun,
@NotNull WrappedVersionState data);
}