diff --git a/.openapi/registry-instance.json b/.openapi/registry-instance.json index 78852a44..01a584ca 100644 --- a/.openapi/registry-instance.json +++ b/.openapi/registry-instance.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "Apicurio Registry API [v2]", - "version": "2.1.0-SNAPSHOT", + "version": "2.2.5.Final", "description": "Apicurio Registry is a datastore for standard event schemas and API designs. Apicurio 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. Apicurio 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.\n\nThe Apicurio 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. \n\nThe supported artifact types include:\n- Apache Avro schema\n- AsyncAPI specification\n- Google protocol buffers\n- GraphQL schema\n- JSON Schema\n- Kafka Connect schema\n- OpenAPI specification\n- Web Services Description Language\n- XML Schema Definition\n\n\n**Important**: The Apicurio Registry REST API is available from `https://MY-REGISTRY-URL/apis/registry/v2` by default. Therefore you must prefix all API operation paths with `../apis/registry/v2` in this case. For example: `../apis/registry/v2/ids/globalIds/{globalId}`.\n", "contact": { "name": "Apicurio", @@ -25,11 +25,11 @@ "200": { "$ref": "#/components/responses/ArtifactContent" }, - "500": { - "$ref": "#/components/responses/ServerError" - }, "404": { "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" } }, "operationId": "getContentById", @@ -55,15 +55,25 @@ "tags": [ "Artifacts" ], + "parameters": [ + { + "name": "dereference", + "description": "Allows the user to specify if the content should be dereferenced when being returned", + "schema": { + "type": "boolean" + }, + "in": "query" + } + ], "responses": { "200": { "$ref": "#/components/responses/ArtifactContent" }, - "500": { - "$ref": "#/components/responses/ServerError" - }, "404": { "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" } }, "operationId": "getContentByGlobalId", @@ -93,11 +103,11 @@ "200": { "$ref": "#/components/responses/ArtifactContent" }, - "500": { - "$ref": "#/components/responses/ServerError" - }, "404": { "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" } }, "operationId": "getContentByHash", @@ -120,7 +130,7 @@ "summary": "Manage the global rules that apply to all artifacts if not otherwise configured.", "get": { "tags": [ - "Admin" + "Global rules" ], "responses": { "200": { @@ -156,7 +166,7 @@ "required": true }, "tags": [ - "Admin" + "Global rules" ], "responses": { "204": { @@ -178,7 +188,7 @@ }, "delete": { "tags": [ - "Admin" + "Global rules" ], "responses": { "204": { @@ -197,7 +207,7 @@ "summary": "Manage the configuration of a single global artifact rule.", "get": { "tags": [ - "Admin" + "Global rules" ], "responses": { "200": { @@ -233,7 +243,7 @@ "required": true }, "tags": [ - "Admin" + "Global rules" ], "responses": { "200": { @@ -259,7 +269,7 @@ }, "delete": { "tags": [ - "Admin" + "Global rules" ], "responses": { "204": { @@ -441,7 +451,7 @@ "summary": "Search for artifacts in the registry.", "get": { "tags": [ - "Artifacts" + "Search" ], "parameters": [ { @@ -525,6 +535,25 @@ "type": "string" }, "in": "query" + }, + { + "name": "globalId", + "description": "Filter by globalId.", + "schema": { + "format": "int64", + "type": "integer" + }, + "in": "query" + }, + { + "name": "contentId", + "description": "Filter by contentId.", + "schema": { + "format": "int64", + "type": "integer" + }, + "in": "query", + "required": false } ], "responses": { @@ -559,7 +588,7 @@ "required": true }, "tags": [ - "Artifacts" + "Search" ], "parameters": [ { @@ -649,6 +678,16 @@ "tags": [ "Admin" ], + "parameters": [ + { + "name": "forBrowser", + "description": "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.", + "schema": { + "type": "boolean" + }, + "in": "query" + } + ], "responses": { "200": { "content": { @@ -659,6 +698,9 @@ } }, "description": "Response when the export is successful." + }, + "500": { + "$ref": "#/components/responses/ServerError" } }, "operationId": "exportData", @@ -683,6 +725,25 @@ "tags": [ "Admin" ], + "parameters": [ + { + "name": "X-Registry-Preserve-GlobalId", + "description": "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.", + "schema": { + "type": "boolean" + }, + "in": "header" + }, + { + "name": "X-Registry-Preserve-ContentId", + "description": "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.", + "schema": { + "type": "boolean" + }, + "in": "header", + "required": false + } + ], "responses": { "201": { "description": "Indicates that the import was successful." @@ -751,187 +812,6 @@ } ] }, - "/groups/{groupId}/artifacts/{artifactId}/meta": { - "summary": "Manage the metadata of a single artifact.", - "get": { - "tags": [ - "Metadata" - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ArtifactMetaData" - } - } - }, - "description": "The artifact's metadata." - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "operationId": "getArtifactMetaData", - "summary": "Get artifact metadata", - "description": "Gets the metadata for an artifact in the registry. The returned metadata includes\nboth generated (read-only) and editable metadata (such as name and description).\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" - }, - "put": { - "requestBody": { - "description": "Updated artifact metadata.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EditableMetaData" - } - } - }, - "required": true - }, - "tags": [ - "Metadata" - ], - "responses": { - "204": { - "description": "The artifact's metadata was updated." - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "operationId": "updateArtifactMetaData", - "summary": "Update artifact metadata", - "description": "Updates the editable parts of the artifact's metadata. Not all metadata fields can\nbe updated. For example, `createdOn` and `createdBy` are both read-only properties.\n\nThis operation can fail for the following reasons:\n\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" - }, - "post": { - "requestBody": { - "description": "The content of an artifact version.", - "content": { - "*/*": { - "schema": { - "$ref": "#/components/schemas/FileContent" - }, - "examples": { - "OpenAPI": { - "value": { - "openapi": "3.0.2", - "info": { - "title": "Empty API", - "version": "1.0.7", - "description": "An example API design using OpenAPI." - }, - "paths": { - "/widgets": { - "get": { - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "string" - } - } - } - }, - "description": "All widgets" - } - }, - "summary": "Get widgets" - } - } - }, - "components": { - "schemas": { - "Widget": { - "title": "Root Type for Widget", - "description": "A sample data type.", - "type": "object", - "properties": { - "property-1": { - "type": "string" - }, - "property-2": { - "type": "boolean" - } - }, - "example": { - "property-1": "value1", - "property-2": true - } - } - } - } - } - } - } - } - }, - "required": true - }, - "tags": [ - "Metadata" - ], - "parameters": [ - { - "name": "canonical", - "description": "Parameter that can be set to `true` to indicate that the server should \"canonicalize\" the content when searching for a matching version. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner.", - "schema": { - "type": "boolean" - }, - "in": "query" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/VersionMetaData" - } - } - }, - "description": "The metadata of the artifact version matching the provided content." - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "operationId": "getArtifactVersionMetaDataByContent", - "summary": "Get artifact version metadata by content", - "description": "Gets the metadata for an artifact that matches the raw content. Searches the registry\nfor a version of the given artifact matching the content provided in the body of the\nPOST.\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* No artifact version matching the provided content exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" - }, - "parameters": [ - { - "name": "groupId", - "description": "The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts.", - "schema": { - "$ref": "#/components/schemas/GroupId" - }, - "in": "path", - "required": true - }, - { - "name": "artifactId", - "description": "The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier.", - "schema": { - "$ref": "#/components/schemas/ArtifactId" - }, - "in": "path", - "required": true - } - ] - }, "/groups/{groupId}/artifacts/{artifactId}/versions/{version}/meta": { "summary": "Manage the metadata for a single version of an artifact in the registry.", "get": { @@ -1044,15 +924,25 @@ "tags": [ "Versions" ], - "responses": { - "404": { - "$ref": "#/components/responses/NotFound" + "parameters": [ + { + "name": "dereference", + "description": "Allows the user to specify if the content should be dereferenced when being returned", + "schema": { + "type": "boolean" + }, + "in": "query" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ArtifactContent" + }, + "404": { + "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" - }, - "200": { - "$ref": "#/components/responses/ArtifactContent" } }, "operationId": "getArtifactVersion", @@ -1373,252 +1263,606 @@ } ] }, - "/groups/{groupId}/artifacts/{artifactId}/test": { - "summary": "Test whether content would pass update rules.", + "/admin/roleMappings/{principalId}": { + "summary": "Manage the configuration of a single role mapping.", + "get": { + "tags": [ + "Admin" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleMapping" + } + } + }, + "description": "When successful, returns the details of a role mapping." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "getRoleMapping", + "summary": "Return a single role mapping", + "description": "Gets the details of a single role mapping (by principalId).\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, "put": { "requestBody": { - "description": "The content of the artifact being tested. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", "content": { - "*/*": { + "application/json": { "schema": { - "$ref": "#/components/schemas/FileContent" + "$ref": "#/components/schemas/UpdateRole" } } }, "required": true }, "tags": [ - "Artifact rules" + "Admin" ], "responses": { "204": { - "description": "When successful, returns \"No Content\" to indicate that the rules passed, and the\ncontent was not updated." + "description": "Response when the update is successful." }, "404": { "$ref": "#/components/responses/NotFound" }, - "409": { - "$ref": "#/components/responses/RuleViolationConflict" - }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "testUpdateArtifact", - "summary": "Test update artifact", - "description": "Tests whether an update to the artifact's content *would* succeed for the provided content.\nUltimately, this applies any rules configured for the artifact against the given content\nto determine whether the rules would pass or fail, but without actually updating the artifact\ncontent.\n\nThe body of the request should be the raw content of the artifact. This is typically in \nJSON format for *most* of the supported types, but may be in another format for a few \n(for example, `PROTOBUF`).\n\nThe update could fail for a number of reasons including:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* The new content violates one of the rules configured for the artifact (HTTP error `409`)\n* The provided artifact type is not recognized (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n\nWhen successful, this operation simply returns a *No Content* response. This response\nindicates that the content is valid against the configured content rules for the \nartifact (or the global rules if no artifact rules are enabled)." + "operationId": "updateRoleMapping", + "summary": "Update a role mapping", + "description": "Updates a single role mapping for one user/principal.\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, - "parameters": [ - { - "name": "groupId", - "description": "The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts.", - "schema": { - "$ref": "#/components/schemas/GroupId" + "delete": { + "tags": [ + "Admin" + ], + "responses": { + "204": { + "description": "Response returned when the delete was successful." }, - "in": "path", - "required": true + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } }, + "operationId": "deleteRoleMapping", + "summary": "Delete a role mapping", + "description": "Deletes a single role mapping, effectively denying access to a user/principal.\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, + "parameters": [ { - "name": "artifactId", - "description": "The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier.", + "name": "principalId", + "description": "Unique id of a principal (typically either a user or service account).", "schema": { - "$ref": "#/components/schemas/ArtifactId" + "type": "string" }, "in": "path", "required": true } ] }, - "/groups/{groupId}/artifacts": { - "summary": "Manage the collection of artifacts within a single group in the registry.", + "/admin/roleMappings": { + "summary": "Collection to manage role mappings for authenticated principals", "get": { "tags": [ - "Artifacts" - ], - "parameters": [ - { - "name": "limit", - "description": "The number of artifacts to return. Defaults to 20.", - "schema": { - "type": "integer" - }, - "in": "query" - }, - { - "name": "offset", - "description": "The number of artifacts to skip before starting the result set. Defaults to 0.", - "schema": { - "type": "integer" - }, - "in": "query" - }, - { - "name": "order", - "description": "Sort order, ascending (`asc`) or descending (`desc`).", - "schema": { - "$ref": "#/components/schemas/SortOrder" - }, - "in": "query" - }, - { - "name": "orderby", - "description": "The field to sort by. Can be one of:\n\n* `name`\n* `createdOn`\n", - "schema": { - "$ref": "#/components/schemas/SortBy" - }, - "in": "query" - } + "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ArtifactSearchResults" + "type": "array", + "items": { + "$ref": "#/components/schemas/RoleMapping" + } } } }, - "description": "On a successful response, returns a bounded set of artifacts." + "description": "A successful response will return the list of role mappings." }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "listArtifactsInGroup", - "summary": "List artifacts in group", - "description": "Returns a list of all artifacts in the group. This list is paged." + "operationId": "listRoleMappings", + "summary": "List all role mappings", + "description": "Gets a list of all role mappings configured in the registry (if any).\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" }, "post": { "requestBody": { - "description": "The content of the artifact being created. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", "content": { - "*/*": { + "application/json": { "schema": { - "$ref": "#/components/schemas/FileContent" - }, - "examples": { - "OpenAPI Example": { - "value": { - "openapi": "3.0.2", - "info": { - "title": "Empty API", - "version": "1.0.7", - "description": "An example API design using OpenAPI." - }, - "paths": { - "/widgets": { - "get": { - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "string" - } - } - } - }, - "description": "All widgets" - } - }, - "summary": "Get widgets" - } - } - }, - "components": { - "schemas": { - "Widget": { - "title": "Root Type for Widget", - "description": "A sample data type.", - "type": "object", - "properties": { - "property-1": { - "type": "string" - }, - "property-2": { - "type": "boolean" - } - }, - "example": { - "property-1": "value1", - "property-2": true - } - } - } - } - } - } + "$ref": "#/components/schemas/RoleMapping" } } }, "required": true }, "tags": [ - "Artifacts" + "Admin" ], - "parameters": [ - { - "name": "X-Registry-ArtifactType", - "description": "Specifies the type of the artifact being added. Possible values include:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)", - "schema": { - "$ref": "#/components/schemas/ArtifactType" - }, - "in": "header" + "responses": { + "204": { + "description": "Returned when the role mapping was successfully created." }, - { - "name": "X-Registry-ArtifactId", - "description": "A client-provided, globally unique identifier for the new artifact.", - "schema": { - "type": "string" + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "createRoleMapping", + "summary": "Create a new role mapping", + "description": "Creates a new mapping between a user/principal and a role.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n\n" + } + }, + "/users/me": { + "summary": "Retrieves information about the current user", + "get": { + "tags": [ + "Users" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserInfo" + } + } }, - "in": "header" + "description": "Response when the endpoint is successfully invoked." }, - { - "name": "X-Registry-Version", - "description": "Specifies the version number of this initial version of the artifact content. This would typically\nbe a simple integer or a SemVer value. If not provided, the server will assign a version number\nautomatically (starting with version `1`).", - "schema": { - "$ref": "#/components/schemas/Version" + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "getCurrentUserInfo", + "summary": "Get current user", + "description": "Returns information about the currently authenticated user." + } + }, + "/ids/contentHashes/{contentHash}/references": { + "get": { + "tags": [ + "Artifacts" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtifactReference" + } + } + } }, - "in": "header" + "description": "A list containing all the references for the artifact with the given content hash." + } + }, + "operationId": "referencesByContentHash", + "summary": "Returns a list with all the references for the artifact with the given hash", + "description": "Returns a list containing all the artifact references using the artifact content hash.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" + }, + "parameters": [ + { + "name": "contentHash", + "description": "SHA-256 content hash for a single artifact content.", + "schema": { + "type": "string" }, - { - "name": "ifExists", - "description": "Set this option to instruct the server on what to do if the artifact already exists.", - "schema": { - "$ref": "#/components/schemas/IfExists" + "in": "path", + "required": true + } + ] + }, + "/ids/contentIds/{contentId}/references": { + "get": { + "tags": [ + "Artifacts" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtifactReference" + } + } + } }, - "in": "query" + "description": "A list containing all the references for the artifact with the given content id." + } + }, + "operationId": "referencesByContentId", + "summary": "Returns a list with all the references for the artifact with the given content id.", + "description": "Returns a list containing all the artifact references using the artifact contentId.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)" + }, + "parameters": [ + { + "name": "contentId", + "description": "Global identifier for a single artifact content.", + "schema": { + "format": "int64", + "type": "integer" }, - { - "name": "canonical", - "description": "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.", - "schema": { - "type": "boolean" + "in": "path", + "required": true + } + ] + }, + "/ids/globalIds/{globalId}/references": { + "get": { + "tags": [ + "Artifacts" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtifactReference" + } + } + } }, - "in": "query" + "description": "A list containing all the references for the artifact with the given global id." + } + }, + "operationId": "referencesByGlobalId", + "summary": "Returns a list with all the references for the artifact with the given global id.", + "description": "Returns a list containing all the artifact references using the artifact global id.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)" + }, + "parameters": [ + { + "name": "globalId", + "description": "Global identifier for an artifact version.", + "schema": { + "format": "int64", + "type": "integer" + }, + "in": "path", + "required": true + } + ] + }, + "/groups/{groupId}/artifacts/{artifactId}/versions/{version}/references": { + "summary": "Manage the references for a single version of an artifact in the registry.", + "get": { + "tags": [ + "Versions" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtifactReference" + } + } + } + }, + "description": "List of all the artifact references for this artifact." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "getArtifactVersionReferences", + "summary": "Get artifact version", + "description": "Retrieves a single version of the artifact content. Both the `artifactId` and the\nunique `version` number must be provided. The `Content-Type` of the response depends \non the artifact type. In most cases, this is `application/json`, but for some types \nit may be different (for example, `PROTOBUF`).\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No version with this `version` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, + "parameters": [ + { + "name": "groupId", + "description": "The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts.", + "schema": { + "$ref": "#/components/schemas/GroupId" + }, + "in": "path", + "required": true + }, + { + "name": "artifactId", + "description": "The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier.", + "schema": { + "$ref": "#/components/schemas/ArtifactId" + }, + "in": "path", + "required": true + }, + { + "name": "version", + "description": "The unique identifier of a specific version of the artifact content.", + "schema": { + "$ref": "#/components/schemas/Version" + }, + "in": "path", + "required": true + } + ] + }, + "/admin/config/properties": { + "summary": "Manage configuration properties.", + "get": { + "tags": [ + "Admin" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ConfigurationProperty" + } + } + } + }, + "description": "On a successful response, returns a list of configuration properties." + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "listConfigProperties", + "summary": "List all configuration properties", + "description": "Returns a list of all configuration properties that have been set. The list is not paged.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" + } + }, + "/admin/config/properties/{propertyName}": { + "summary": "Manage a single configuration property (by name).", + "get": { + "tags": [ + "Admin" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfigurationProperty" + } + } + }, + "description": "The configuration property value." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "getConfigProperty", + "summary": "Get the value of a configuration property", + "description": "Returns the value of a single configuration property.\n\nThis operation may fail for one of the following reasons:\n\n* Property not found or not configured (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, + "put": { + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateConfigurationProperty" + } + } + }, + "required": true + }, + "tags": [ + "Admin" + ], + "responses": { + "204": { + "description": "The configuration property was updated." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "updateConfigProperty", + "summary": "Update a configuration property", + "description": "Updates the value of a single configuration property.\n\nThis operation may fail for one of the following reasons:\n\n* Property not found or not configured (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, + "delete": { + "tags": [ + "Admin" + ], + "responses": { + "204": { + "description": "The configuration property was deleted." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "resetConfigProperty", + "summary": "Reset a configuration property", + "description": "Resets the value of a single configuration property. This will return the property to\nits default value (see external documentation for supported properties and their default\nvalues).\n\nThis operation may fail for one of the following reasons:\n\n* Property not found or not configured (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, + "parameters": [ + { + "name": "propertyName", + "description": "The name of a configuration property.", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ] + }, + "/system/limits": { + "summary": "Retrieve resource limits information", + "get": { + "tags": [ + "System" + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Limits" + } + } + }, + "description": "On success, returns resource limits" }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "getResourceLimits", + "summary": "Get resource limits information", + "description": "This operation retrieves the list of limitations on used resources, that are applied on the current instance of Registry." + } + }, + "/groups/{groupId}/artifacts/{artifactId}": { + "summary": "Manage a single artifact.", + "get": { + "tags": [ + "Artifacts" + ], + "parameters": [ { - "name": "X-Registry-Description", - "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.", + "name": "dereference", + "description": "Allows the user to specify if the content should be dereferenced when being returned", "schema": { - "$ref": "#/components/schemas/ArtifactDescription" + "type": "boolean" }, - "in": "header", + "in": "query", "required": false + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ArtifactContent" + }, + "404": { + "$ref": "#/components/responses/NotFound" }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "getLatestArtifact", + "summary": "Get latest artifact", + "description": "Returns the latest version of the artifact in its raw form. The `Content-Type` of the\nresponse depends on the artifact type. In most cases, this is `application/json`, but \nfor some types it may be different (for example, `PROTOBUF`).\n\nThis operation may fail for one of the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, + "put": { + "requestBody": { + "description": "The new content of the artifact being updated. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", + "content": { + "*/*": { + "schema": {}, + "examples": { + "OpenAPI Example": { + "value": { + "openapi": "3.0.2", + "info": { + "title": "Empty API", + "version": "1.0.7", + "description": "An example API design using OpenAPI." + }, + "paths": { + "/widgets": { + "get": { + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "description": "All widgets" + } + }, + "summary": "Get widgets" + } + } + }, + "components": { + "schemas": { + "Widget": { + "title": "Root Type for Widget", + "description": "A sample data type.", + "type": "object", + "properties": { + "property-1": { + "type": "string" + }, + "property-2": { + "type": "boolean" + } + }, + "example": { + "property-1": "value1", + "property-2": true + } + } + } + } + } + } + } + }, + "application/create.extended+json": { + "schema": { + "$ref": "#/components/schemas/ContentCreateRequest" + } + } + }, + "required": true + }, + "tags": [ + "Artifacts" + ], + "parameters": [ { - "name": "X-Registry-Description-Encoded", - "description": "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.", + "name": "X-Registry-Version", + "description": "Specifies the version number of this new version of the artifact content. This would typically\nbe a simple integer or a SemVer value. If not provided, the server will assign a version number\nautomatically.", "schema": { - "$ref": "#/components/schemas/EncodedArtifactDescription" + "$ref": "#/components/schemas/Version" }, "in": "header" }, { "name": "X-Registry-Name", - "description": "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.", + "description": "Specifies the artifact name of this new version of the artifact content. Name must be ASCII-only string. If this is not\nprovided, the server will extract the name from the artifact content.", "schema": { "$ref": "#/components/schemas/ArtifactName" }, @@ -1626,11 +1870,27 @@ }, { "name": "X-Registry-Name-Encoded", - "description": "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.", + "description": "Specifies the artifact name of this new version of the artifact content. Value of this must be Base64 encoded string. If this is not provided, the server will extract the name from the artifact content.", "schema": { "$ref": "#/components/schemas/EncodedArtifactName" }, "in": "header" + }, + { + "name": "X-Registry-Description", + "description": "Specifies the artifact description of this new version of the artifact content. Description must be ASCII-only string. If this is not provided, the server will extract the description from the artifact content.", + "schema": { + "$ref": "#/components/schemas/ArtifactDescription" + }, + "in": "header" + }, + { + "name": "X-Registry-Description-Encoded", + "description": "Specifies the artifact description of this new version of the artifact content. Value of this must be Base64 encoded string. If this is not provided, the server will extract the description from the artifact content.", + "schema": { + "$ref": "#/components/schemas/EncodedArtifactDescription" + }, + "in": "header" } ], "responses": { @@ -1642,21 +1902,21 @@ } } }, - "description": "Artifact was successfully created." + "description": "When successful, returns the updated artifact metadata." }, - "400": { - "$ref": "#/components/responses/BadRequest" + "404": { + "$ref": "#/components/responses/NotFound" }, "409": { - "$ref": "#/components/responses/RuleViolationConflict" + "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "createArtifact", - "summary": "Create artifact", - "description": "Creates a new artifact by posting the artifact content. The body of the request should\nbe the raw content of the artifact. This is typically in JSON format for *most* of the \nsupported types, but may be in another format for a few (for example, `PROTOBUF`).\n\nThe registry attempts to figure out what kind of artifact is being added from the\nfollowing supported list:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n\nAlternatively, you can specify the artifact type using the `X-Registry-ArtifactType` \nHTTP request header, or include a hint in the request's `Content-Type`. For example:\n\n```\nContent-Type: application/json; artifactType=AVRO\n```\n\nAn artifact is created using the content provided in the body of the request. This\ncontent is created under a unique artifact ID that can be provided in the request\nusing the `X-Registry-ArtifactId` request header. If not provided in the request,\nthe server generates a unique ID for the artifact. It is typically recommended\nthat callers provide the ID, because this is typically a meaningful identifier, \nand for most use cases should be supplied by the caller.\n\nIf an artifact with the provided artifact ID already exists, the default behavior\nis for the server to reject the content with a 409 error. However, the caller can\nsupply the `ifExists` query parameter to alter this default behavior. The `ifExists`\nquery parameter can have one of the following values:\n\n* `FAIL` (*default*) - server rejects the content with a 409 error\n* `UPDATE` - server updates the existing artifact and returns the new metadata\n* `RETURN` - server does not create or add content to the server, but instead \nreturns the metadata for the existing artifact\n* `RETURN_OR_UPDATE` - server returns an existing **version** that matches the \nprovided content if such a version exists, otherwise a new version is created\n\nThis operation may fail for one of the following reasons:\n\n* An invalid `ArtifactType` was indicated (HTTP error `400`)\n* No `ArtifactType` was indicated and the server could not determine one from the content (HTTP error `400`)\n* Provided content (request body) was empty (HTTP error `400`)\n* An artifact with the provided ID already exists (HTTP error `409`)\n* The content violates one of the configured global rules (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" + "operationId": "updateArtifact", + "summary": "Update artifact", + "description": "Updates an artifact by uploading new content. The body of the request can\nbe the raw content of the artifact or a JSON object containing both the raw content and\na set of references to other artifacts.. This is typically in JSON format for *most*\nof the supported types, but may be in another format for a few (for example, `PROTOBUF`).\nThe type of the content should be compatible with the artifact's type (it would be\nan error to update an `AVRO` artifact with new `OPENAPI` content, for example).\n\nThe update could fail for a number of reasons including:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* The new content violates one of the rules configured for the artifact (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n\nWhen successful, this creates a new version of the artifact, making it the most recent\n(and therefore official) version of the artifact." }, "delete": { "tags": [ @@ -1664,57 +1924,105 @@ ], "responses": { "204": { - "description": "When the delete operation is successful, a simple 204 is returned." + "description": "Returned when the artifact was successfully deleted." + }, + "404": { + "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "deleteArtifactsInGroup", - "summary": "Deletes all artifacts in a group", - "description": "Deletes all of the artifacts that exist in a given group." + "operationId": "deleteArtifact", + "summary": "Delete artifact", + "description": "Deletes an artifact completely, resulting in all versions of the artifact also being\ndeleted. This may fail for one of the following reasons:\n\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "parameters": [ { "name": "groupId", - "description": "Unique ID of an artifact group.", + "description": "The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts.", "schema": { "$ref": "#/components/schemas/GroupId" }, "in": "path", "required": true + }, + { + "name": "artifactId", + "description": "The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier.", + "schema": { + "$ref": "#/components/schemas/ArtifactId" + }, + "in": "path", + "required": true } ] }, - "/groups/{groupId}/artifacts/{artifactId}": { - "summary": "Manage a single artifact.", + "/groups/{groupId}/artifacts": { + "summary": "Manage the collection of artifacts within a single group in the registry.", "get": { "tags": [ "Artifacts" ], + "parameters": [ + { + "name": "limit", + "description": "The number of artifacts to return. Defaults to 20.", + "schema": { + "type": "integer" + }, + "in": "query" + }, + { + "name": "offset", + "description": "The number of artifacts to skip before starting the result set. Defaults to 0.", + "schema": { + "type": "integer" + }, + "in": "query" + }, + { + "name": "order", + "description": "Sort order, ascending (`asc`) or descending (`desc`).", + "schema": { + "$ref": "#/components/schemas/SortOrder" + }, + "in": "query" + }, + { + "name": "orderby", + "description": "The field to sort by. Can be one of:\n\n* `name`\n* `createdOn`\n", + "schema": { + "$ref": "#/components/schemas/SortBy" + }, + "in": "query" + } + ], "responses": { "200": { - "$ref": "#/components/responses/ArtifactContent" - }, - "404": { - "$ref": "#/components/responses/NotFound" + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArtifactSearchResults" + } + } + }, + "description": "On a successful response, returns a bounded set of artifacts." }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "getLatestArtifact", - "summary": "Get latest artifact", - "description": "Returns the latest version of the artifact in its raw form. The `Content-Type` of the\nresponse depends on the artifact type. In most cases, this is `application/json`, but \nfor some types it may be different (for example, `PROTOBUF`).\n\nThis operation may fail for one of the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + "operationId": "listArtifactsInGroup", + "summary": "List artifacts in group", + "description": "Returns a list of all artifacts in the group. This list is paged." }, - "put": { + "post": { "requestBody": { - "description": "The new content of the artifact being updated. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", + "description": "The content of the artifact being created. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", "content": { "*/*": { - "schema": { - "$ref": "#/components/schemas/FileContent" - }, + "schema": {}, "examples": { "OpenAPI Example": { "value": { @@ -1770,6 +2078,11 @@ } } } + }, + "application/create.extended+json": { + "schema": { + "$ref": "#/components/schemas/ContentCreateRequest" + } } }, "required": true @@ -1779,44 +2092,77 @@ ], "parameters": [ { - "name": "X-Registry-Version", - "description": "Specifies the version number of this new version of the artifact content. This would typically\nbe a simple integer or a SemVer value. If not provided, the server will assign a version number\nautomatically.", + "name": "X-Registry-ArtifactType", + "description": "Specifies the type of the artifact being added. Possible values include:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)", "schema": { - "$ref": "#/components/schemas/Version" + "$ref": "#/components/schemas/ArtifactType" }, "in": "header" }, { - "name": "X-Registry-Name", - "description": "Specifies the artifact name of this new version of the artifact content. Name must be ASCII-only string. If this is not\nprovided, the server will extract the name from the artifact content.", + "name": "X-Registry-ArtifactId", + "description": "A client-provided, globally unique identifier for the new artifact.", "schema": { - "$ref": "#/components/schemas/ArtifactName" + "type": "string" }, "in": "header" }, { - "name": "X-Registry-Name-Encoded", - "description": "Specifies the artifact name of this new version of the artifact content. Value of this must be Base64 encoded string. If this is not provided, the server will extract the name from the artifact content.", + "name": "X-Registry-Version", + "description": "Specifies the version number of this initial version of the artifact content. This would typically\nbe a simple integer or a SemVer value. If not provided, the server will assign a version number\nautomatically (starting with version `1`).", "schema": { - "$ref": "#/components/schemas/EncodedArtifactName" + "$ref": "#/components/schemas/Version" }, "in": "header" }, + { + "name": "ifExists", + "description": "Set this option to instruct the server on what to do if the artifact already exists.", + "schema": { + "$ref": "#/components/schemas/IfExists" + }, + "in": "query" + }, + { + "name": "canonical", + "description": "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.", + "schema": { + "type": "boolean" + }, + "in": "query" + }, { "name": "X-Registry-Description", - "description": "Specifies the artifact description of this new version of the artifact content. Description must be ASCII-only string. If this is not provided, the server will extract the description from the artifact content.", + "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.", "schema": { "$ref": "#/components/schemas/ArtifactDescription" }, - "in": "header" + "in": "header", + "required": false }, { "name": "X-Registry-Description-Encoded", - "description": "Specifies the artifact description of this new version of the artifact content. Value of this must be Base64 encoded string. If this is not provided, the server will extract the description from the artifact content.", + "description": "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.", "schema": { "$ref": "#/components/schemas/EncodedArtifactDescription" }, "in": "header" + }, + { + "name": "X-Registry-Name", + "description": "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.", + "schema": { + "$ref": "#/components/schemas/ArtifactName" + }, + "in": "header" + }, + { + "name": "X-Registry-Name-Encoded", + "description": "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.", + "schema": { + "$ref": "#/components/schemas/EncodedArtifactName" + }, + "in": "header" } ], "responses": { @@ -1828,21 +2174,21 @@ } } }, - "description": "When successful, returns the updated artifact metadata." + "description": "Artifact was successfully created." }, - "404": { - "$ref": "#/components/responses/NotFound" + "400": { + "$ref": "#/components/responses/BadRequest" }, "409": { - "$ref": "#/components/responses/Conflict" + "$ref": "#/components/responses/RuleViolationConflict" }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "updateArtifact", - "summary": "Update artifact", - "description": "Updates an artifact by uploading new content. The body of the request should\nbe the raw content of the artifact. This is typically in JSON format for *most*\nof the supported types, but may be in another format for a few (for example, `PROTOBUF`).\nThe type of the content should be compatible with the artifact's type (it would be\nan error to update an `AVRO` artifact with new `OPENAPI` content, for example).\n\nThe update could fail for a number of reasons including:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* The new content violates one of the rules configured for the artifact (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n\nWhen successful, this creates a new version of the artifact, making it the most recent\n(and therefore official) version of the artifact." + "operationId": "createArtifact", + "summary": "Create artifact", + "description": "Creates a new artifact by posting the artifact content. The body of the request should\nbe the raw content of the artifact. This is typically in JSON format for *most* of the \nsupported types, but may be in another format for a few (for example, `PROTOBUF`).\n\nThe registry attempts to figure out what kind of artifact is being added from the\nfollowing supported list:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n\nAlternatively, you can specify the artifact type using the `X-Registry-ArtifactType` \nHTTP request header, or include a hint in the request's `Content-Type`. For example:\n\n```\nContent-Type: application/json; artifactType=AVRO\n```\n\nAn artifact is created using the content provided in the body of the request. This\ncontent is created under a unique artifact ID that can be provided in the request\nusing the `X-Registry-ArtifactId` request header. If not provided in the request,\nthe server generates a unique ID for the artifact. It is typically recommended\nthat callers provide the ID, because this is typically a meaningful identifier, \nand for most use cases should be supplied by the caller.\n\nIf an artifact with the provided artifact ID already exists, the default behavior\nis for the server to reject the content with a 409 error. However, the caller can\nsupply the `ifExists` query parameter to alter this default behavior. The `ifExists`\nquery parameter can have one of the following values:\n\n* `FAIL` (*default*) - server rejects the content with a 409 error\n* `UPDATE` - server updates the existing artifact and returns the new metadata\n* `RETURN` - server does not create or add content to the server, but instead \nreturns the metadata for the existing artifact\n* `RETURN_OR_UPDATE` - server returns an existing **version** that matches the \nprovided content if such a version exists, otherwise a new version is created\n\nThis operation may fail for one of the following reasons:\n\n* An invalid `ArtifactType` was indicated (HTTP error `400`)\n* No `ArtifactType` was indicated and the server could not determine one from the content (HTTP error `400`)\n* Provided content (request body) was empty (HTTP error `400`)\n* An artifact with the provided ID already exists (HTTP error `409`)\n* The content violates one of the configured global rules (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ @@ -1850,18 +2196,60 @@ ], "responses": { "204": { - "description": "Returned when the artifact was successfully deleted." + "description": "When the delete operation is successful, a simple 204 is returned." + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "operationId": "deleteArtifactsInGroup", + "summary": "Deletes all artifacts in a group", + "description": "Deletes all of the artifacts that exist in a given group." + }, + "parameters": [ + { + "name": "groupId", + "description": "Unique ID of an artifact group.", + "schema": { + "$ref": "#/components/schemas/GroupId" + }, + "in": "path", + "required": true + } + ] + }, + "/groups/{groupId}/artifacts/{artifactId}/test": { + "summary": "Test whether content would pass update rules.", + "put": { + "requestBody": { + "description": "The content of the artifact being tested. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", + "content": { + "*/*": { + "schema": {} + } + }, + "required": true + }, + "tags": [ + "Artifact rules" + ], + "responses": { + "204": { + "description": "When successful, returns \"No Content\" to indicate that the rules passed, and the\ncontent was not updated." }, "404": { "$ref": "#/components/responses/NotFound" }, + "409": { + "$ref": "#/components/responses/RuleViolationConflict" + }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "deleteArtifact", - "summary": "Delete artifact", - "description": "Deletes an artifact completely, resulting in all versions of the artifact also being\ndeleted. This may fail for one of the following reasons:\n\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" + "operationId": "testUpdateArtifact", + "summary": "Test update artifact", + "description": "Tests whether an update to the artifact's content *would* succeed for the provided content.\nUltimately, this applies any rules configured for the artifact against the given content\nto determine whether the rules would pass or fail, but without actually updating the artifact\ncontent.\n\nThe body of the request should be the raw content of the artifact. This is typically in \nJSON format for *most* of the supported types, but may be in another format for a few \n(for example, `PROTOBUF`).\n\nThe update could fail for a number of reasons including:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* The new content violates one of the rules configured for the artifact (HTTP error `409`)\n* The provided artifact type is not recognized (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n\nWhen successful, this operation simply returns a *No Content* response. This response\nindicates that the content is valid against the configured content rules for the \nartifact (or the global rules if no artifact rules are enabled)." }, "parameters": [ { @@ -1944,12 +2332,10 @@ }, "post": { "requestBody": { - "description": "The content of the artifact version being created. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", + "description": "The content of the artifact version being created or the content and a set of references to other artifacts. This is often, but not always, JSON data\nrepresenting one of the supported artifact types:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n", "content": { "*/*": { - "schema": { - "$ref": "#/components/schemas/FileContent" - }, + "schema": {}, "examples": { "OpenAPI Example": { "value": { @@ -2005,6 +2391,11 @@ } } } + }, + "application/create.extended+json": { + "schema": { + "$ref": "#/components/schemas/ContentCreateRequest" + } } }, "required": true @@ -2077,7 +2468,7 @@ }, "operationId": "createArtifactVersion", "summary": "Create artifact version", - "description": "Creates a new version of the artifact by uploading new content. The configured rules for\nthe artifact are applied, and if they all pass, the new content is added as the most recent \nversion of the artifact. If any of the rules fail, an error is returned.\n\nThe body of the request should be the raw content of the new artifact version, and the type\nof that content should match the artifact's type (for example if the artifact type is `AVRO`\nthen the content of the request should be an Apache Avro document).\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* The new content violates one of the rules configured for the artifact (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" + "description": "Creates a new version of the artifact by uploading new content. The configured rules for\nthe artifact are applied, and if they all pass, the new content is added as the most recent \nversion of the artifact. If any of the rules fail, an error is returned.\n\nThe body of the request can be the raw content of the new artifact version, or the raw content \nand a set of references pointing to other artifacts, and the type\nof that content should match the artifact's type (for example if the artifact type is `AVRO`\nthen the content of the request should be an Apache Avro document).\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* The new content violates one of the rules configured for the artifact (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" }, "parameters": [ { @@ -2085,189 +2476,199 @@ "description": "The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts.", "schema": { "$ref": "#/components/schemas/GroupId" - }, - "in": "path", - "required": true - }, - { - "name": "artifactId", - "description": "The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier.", - "schema": { - "$ref": "#/components/schemas/ArtifactId" - }, - "in": "path", - "required": true - } - ] - }, - "/admin/roleMappings/{principalId}": { - "summary": "Manage the configuration of a single role mapping.", - "get": { - "tags": [ - "Admin" - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RoleMapping" - } - } - }, - "description": "When successful, returns the details of a role mapping." - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "operationId": "getRoleMapping", - "summary": "Return a single role mapping", - "description": "Gets the details of a single role mapping (by principalId).\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" - }, - "put": { - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateRole" - } - } - }, - "required": true - }, - "tags": [ - "Admin" - ], - "responses": { - "204": { - "description": "Response when the update is successful." - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "operationId": "updateRoleMapping", - "summary": "Update a role mapping", - "description": "Updates a single role mapping for one user/principal.\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" - }, - "delete": { - "tags": [ - "Admin" - ], - "responses": { - "204": { - "description": "Response returned when the delete was successful." - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "operationId": "deleteRoleMapping", - "summary": "Delete a role mapping", - "description": "Deletes a single role mapping, effectively denying access to a user/principal.\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" - }, - "parameters": [ + }, + "in": "path", + "required": true + }, { - "name": "principalId", - "description": "Unique id of a principal (typically either a user or service account).", + "name": "artifactId", + "description": "The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier.", "schema": { - "type": "string" + "$ref": "#/components/schemas/ArtifactId" }, "in": "path", "required": true } ] }, - "/admin/roleMappings": { - "summary": "Collection to manage role mappings for authenticated principals", + "/groups/{groupId}/artifacts/{artifactId}/meta": { + "summary": "Manage the metadata of a single artifact.", "get": { "tags": [ - "Admin" + "Metadata" ], "responses": { "200": { "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RoleMapping" - } + "$ref": "#/components/schemas/ArtifactMetaData" } } }, - "description": "A successful response will return the list of role mappings." + "description": "The artifact's metadata." + }, + "404": { + "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "listRoleMappings", - "summary": "List all role mappings", - "description": "Gets a list of all role mappings configured in the registry (if any).\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" + "operationId": "getArtifactMetaData", + "summary": "Get artifact metadata", + "description": "Gets the metadata for an artifact in the registry. The returned metadata includes\nboth generated (read-only) and editable metadata (such as name and description).\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, - "post": { + "put": { "requestBody": { + "description": "Updated artifact metadata.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RoleMapping" + "$ref": "#/components/schemas/EditableMetaData" } } }, "required": true }, "tags": [ - "Admin" + "Metadata" ], "responses": { "204": { - "description": "Returned when the role mapping was successfully created." + "description": "The artifact's metadata was updated." + }, + "404": { + "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "createRoleMapping", - "summary": "Create a new role mapping", - "description": "Creates a new mapping between a user/principal and a role.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n\n" - } - }, - "/users/me": { - "summary": "Retrieves information about the current user", - "get": { + "operationId": "updateArtifactMetaData", + "summary": "Update artifact metadata", + "description": "Updates the editable parts of the artifact's metadata. Not all metadata fields can\nbe updated. For example, `createdOn` and `createdBy` are both read-only properties.\n\nThis operation can fail for the following reasons:\n\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" + }, + "post": { + "requestBody": { + "description": "The content of an artifact version.", + "content": { + "*/*": { + "schema": {}, + "examples": { + "OpenAPI": { + "value": { + "openapi": "3.0.2", + "info": { + "title": "Empty API", + "version": "1.0.7", + "description": "An example API design using OpenAPI." + }, + "paths": { + "/widgets": { + "get": { + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "description": "All widgets" + } + }, + "summary": "Get widgets" + } + } + }, + "components": { + "schemas": { + "Widget": { + "title": "Root Type for Widget", + "description": "A sample data type.", + "type": "object", + "properties": { + "property-1": { + "type": "string" + }, + "property-2": { + "type": "boolean" + } + }, + "example": { + "property-1": "value1", + "property-2": true + } + } + } + } + } + } + } + } + }, + "required": true + }, "tags": [ - "Users" + "Metadata" + ], + "parameters": [ + { + "name": "canonical", + "description": "Parameter that can be set to `true` to indicate that the server should \"canonicalize\" the content when searching for a matching version. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner.", + "schema": { + "type": "boolean" + }, + "in": "query" + } ], "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserInfo" + "$ref": "#/components/schemas/VersionMetaData" } } }, - "description": "Response when the endpoint is successfully invoked." + "description": "The metadata of the artifact version matching the provided content." + }, + "404": { + "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, - "operationId": "getCurrentUserInfo", - "summary": "Get current user", - "description": "Returns information about the currently authenticated user." - } + "operationId": "getArtifactVersionMetaDataByContent", + "summary": "Get artifact version metadata by content", + "description": "Gets the metadata for an artifact that matches the raw content. Searches the registry\nfor a version of the given artifact matching the content provided in the body of the\nPOST.\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* No artifact version matching the provided content exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" + }, + "parameters": [ + { + "name": "groupId", + "description": "The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts.", + "schema": { + "$ref": "#/components/schemas/GroupId" + }, + "in": "path", + "required": true + }, + { + "name": "artifactId", + "description": "The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier.", + "schema": { + "$ref": "#/components/schemas/ArtifactId" + }, + "in": "path", + "required": true + } + ] } }, "components": { @@ -2308,95 +2709,6 @@ } } }, - "VersionMetaData": { - "title": "Root Type for ArtifactVersionMetaData", - "description": "", - "required": [ - "createdOn", - "createdBy", - "version", - "type", - "globalId", - "id", - "contentId" - ], - "type": "object", - "properties": { - "version": { - "type": "string" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "createdBy": { - "type": "string" - }, - "createdOn": { - "format": "utc-date", - "type": "string" - }, - "type": { - "$ref": "#/components/schemas/ArtifactType", - "description": "" - }, - "globalId": { - "format": "int64", - "description": "", - "type": "integer" - }, - "state": { - "$ref": "#/components/schemas/ArtifactState", - "description": "" - }, - "id": { - "$ref": "#/components/schemas/ArtifactId", - "description": "" - }, - "labels": { - "description": "", - "type": "array", - "items": { - "type": "string" - } - }, - "properties": { - "$ref": "#/components/schemas/Properties", - "description": "" - }, - "groupId": { - "$ref": "#/components/schemas/GroupId", - "description": "" - }, - "contentId": { - "format": "int64", - "description": "", - "type": "integer" - } - }, - "example": { - "groupId": "My-Group", - "id": "my-artifact-id", - "version": 1221432, - "type": "PROTOBUF", - "name": "Artifact Name", - "description": "The description of the artifact", - "createdBy": "user1", - "createdOn": "2019-05-17T12:00:00Z", - "globalId": 183282932983, - "contentId": 12347, - "labels": [ - "label-1", - "label-2" - ], - "properties": { - "custom-1": "foo", - "custom-2": "bar" - } - } - }, "Rule": { "title": "Root Type for Rule", "description": "", @@ -2549,33 +2861,319 @@ } } }, - "SearchedVersion": { - "description": "Models a single artifact from the result set returned when searching for artifacts.", + "RuleViolationCause": { + "title": "Root Type for RuleViolationCause", + "description": "", + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "context": { + "type": "string" + } + }, + "example": { + "description": "External documentation URL is not valid (it must be formatted as a URL).", + "context": "/info/externalDocs[url]" + } + }, + "GroupId": { + "description": "An ID of a single artifact group.", + "type": "string", + "example": "\"my-group\"" + }, + "ArtifactId": { + "description": "The ID of a single artifact.", + "type": "string", + "example": "\"example-artifact\"" + }, + "Version": { + "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.", + "type": "string", + "example": "\"3.1.6\"" + }, + "LogConfiguration": { + "description": "", + "required": [ + "level" + ], + "type": "object", + "properties": { + "level": { + "$ref": "#/components/schemas/LogLevel", + "description": "" + } + } + }, + "NamedLogConfiguration": { + "description": "", + "type": "object", + "allOf": [ + { + "required": [ + "name" + ], + "type": "object", + "properties": { + "name": { + "description": "", + "type": "string" + } + } + }, + { + "$ref": "#/components/schemas/LogConfiguration" + } + ] + }, + "Properties": { + "description": "User-defined name-value pairs. Name and value must be strings.", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "x-codegen-inline": true, + "x-codegen-type": "StringMap" + }, + "IfExists": { + "description": "", + "enum": [ + "FAIL", + "UPDATE", + "RETURN", + "RETURN_OR_UPDATE" + ], + "type": "string" + }, + "SortBy": { + "description": "", + "enum": [ + "name", + "createdOn" + ], + "type": "string" + }, + "LogLevel": { + "description": "", + "enum": [ + "DEBUG", + "TRACE", + "WARN", + "ERROR", + "SEVERE", + "WARNING", + "INFO", + "CONFIG", + "FINE", + "FINER", + "FINEST" + ], + "type": "string", + "x-codegen-package": "io.apicurio.registry.types" + }, + "SystemInfo": { + "title": "Root Type for SystemInfo", + "description": "", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "version": { + "type": "string" + }, + "builtOn": { + "format": "utc-date", + "type": "string" + } + }, + "example": { + "name": "Apicurio Registry (SQL)", + "description": "The Apicurio Registry application.", + "version": "2.0.0.Final", + "builtOn": "2021-03-19T12:55:00Z" + } + }, + "FileContent": { + "format": "binary", + "type": "string", + "x-codegen-inline": true + }, + "RoleMapping": { + "description": "The mapping between a user/principal and their role.", + "required": [ + "principalId", + "role" + ], + "type": "object", + "properties": { + "principalId": { + "description": "", + "type": "string" + }, + "role": { + "$ref": "#/components/schemas/RoleType", + "description": "" + }, + "principalName": { + "description": "A friendly name for the principal.", + "type": "string" + } + }, + "example": { + "principalId": "svc_account_84874587_123484", + "principalName": "famartin-svc-account", + "role": "READ_ONLY" + } + }, + "RoleType": { + "description": "", + "enum": [ + "READ_ONLY", + "DEVELOPER", + "ADMIN" + ], + "type": "string", + "x-codegen-package": "io.apicurio.registry.types" + }, + "UpdateRole": { + "title": "Root Type for UpdateRole", + "description": "", + "required": [ + "role" + ], + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/RoleType" + } + }, + "example": { + "role": "READ_ONLY" + } + }, + "UserInfo": { + "title": "Root Type for UserInfo", + "description": "Information about a single user.", + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "admin": { + "type": "boolean" + }, + "developer": { + "type": "boolean" + }, + "viewer": { + "type": "boolean" + } + }, + "example": { + "username": "dprince", + "displayName": "Diana Prince", + "admin": true, + "developer": false, + "viewer": false + } + }, + "EncodedArtifactName": { + "description": "Base64 encoded name of the artifact.", + "type": "string", + "example": "\"QXJ0aWZhY3QgbmFtZQo=\"", + "x-codegen-inline": true + }, + "EncodedArtifactDescription": { + "description": "Base64 encoded description of the artifact.", + "type": "string", + "example": "\"QXJ0aWZhY3QgZGVzY3JpcHRpb24K\"", + "x-codegen-inline": true + }, + "ArtifactName": { + "description": "Name of the artifact.", + "type": "string", + "example": "\"Artifact name\"", + "x-codegen-inline": true + }, + "ArtifactDescription": { + "description": "Description of the artifact.", + "type": "string", + "example": "\"Artifact description\"", + "x-codegen-inline": true + }, + "DownloadRef": { + "title": "Root Type for Download", + "description": "Models a download \"link\". Useful for browser use-cases.", + "required": [ + "downloadId" + ], + "type": "object", + "properties": { + "downloadId": { + "type": "string" + }, + "href": { + "type": "string" + } + }, + "example": { + "downloadId": "247-4987490-297845", + "href": "https://54321.registry.examples.org/apis/registry/v2/downloads/247-4987490-297845" + } + }, + "ArtifactMetaData": { + "title": "Root Type for ArtifactMetaData", + "description": "", "required": [ + "id", "createdBy", "createdOn", + "modifiedBy", + "modifiedOn", + "version", "type", - "state", "globalId", - "version", + "state", + "group", "contentId" ], "type": "object", "properties": { "name": { - "description": "", "type": "string" }, "description": { - "description": "", + "type": "string" + }, + "createdBy": { "type": "string" }, "createdOn": { "format": "utc-date", - "description": "", + "type": "string", + "x-codegen-formatPattern": "yyyy-MM-dd'T'HH:mm:ssZ" + }, + "modifiedBy": { "type": "string" }, - "createdBy": { + "modifiedOn": { + "format": "utc-date", + "type": "string", + "x-codegen-formatPattern": "yyyy-MM-dd'T'HH:mm:ssZ" + }, + "id": { + "$ref": "#/components/schemas/ArtifactId", + "description": "" + }, + "version": { "description": "", "type": "string" }, @@ -2583,124 +3181,74 @@ "$ref": "#/components/schemas/ArtifactType", "description": "" }, - "labels": { + "globalId": { + "format": "int64", "description": "", - "type": "array", - "items": { - "type": "string" - } + "type": "integer" }, "state": { "$ref": "#/components/schemas/ArtifactState", "description": "" }, - "globalId": { - "format": "int64", - "description": "", - "type": "integer" - }, - "version": { + "labels": { "description": "", - "type": "string" + "type": "array", + "items": { + "type": "string" + } }, "properties": { "$ref": "#/components/schemas/Properties", "description": "" }, + "groupId": { + "$ref": "#/components/schemas/GroupId", + "description": "" + }, "contentId": { "format": "int64", "description": "", "type": "integer" + }, + "references": { + "description": "", + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtifactReference" + } } }, "example": { - "name": "Artifact Version Name", - "description": "Description of the artifact version", + "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": [ - "current", - "internal" + "label-1", + "label-2" ], - "type": "AVRO", - "state": "ENABLED", - "createdOn": "2018-02-10T09:30Z", - "createdBy": "some text", - "globalId": 37, - "version": 85, - "properties": {}, - "contentId": 62 - } - }, - "RuleViolationError": { - "title": "Root Type for Error", - "description": "All error responses, whether `4xx` or `5xx` will include one of these as the response\nbody.", - "type": "object", - "allOf": [ - { - "required": [ - "causes" - ], - "type": "object", - "properties": { - "causes": { - "description": "List of rule violation causes.", - "type": "array", - "items": { - "$ref": "#/components/schemas/RuleViolationCause" - } - } - } + "properties": { + "custom-1": "foo", + "custom-2": "bar" }, - { - "$ref": "#/components/schemas/Error" - } - ], - "example": { - "error_code": 409, - "message": "Artifact failed validation", - "causes": [ - { - "description": "API is missing a title", - "context": "/info[title]" - }, + "references": [ { - "description": "Operation IDs must be unique", - "context": "/paths[/invoices]/put[operationId]" + "groupId": "mygroup", + "artifactId": "13842090-2ce3-11ec-8d3d-0242ac130003", + "version": 2, + "name": "foo.bar.Open" } ] } }, - "RuleViolationCause": { - "title": "Root Type for RuleViolationCause", - "description": "", - "type": "object", - "properties": { - "description": { - "type": "string" - }, - "context": { - "type": "string" - } - }, - "example": { - "description": "External documentation URL is not valid (it must be formatted as a URL).", - "context": "/info/externalDocs[url]" - } - }, - "GroupId": { - "description": "An ID of a single artifact group.", - "type": "string", - "example": "\"my-group\"" - }, - "ArtifactId": { - "description": "The ID of a single artifact.", - "type": "string", - "example": "\"example-artifact\"" - }, - "Version": { - "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.", - "type": "string", - "example": "\"3.1.6\"" - }, "SearchedArtifact": { "description": "Models a single artifact from the result set returned when searching for artifacts.", "required": [ @@ -2728,7 +3276,8 @@ "createdOn": { "format": "utc-date", "description": "", - "type": "string" + "type": "string", + "x-codegen-formatPattern": "yyyy-MM-dd'T'HH:mm:ssZ" }, "createdBy": { "description": "", @@ -2752,7 +3301,8 @@ "modifiedOn": { "format": "utc-date", "description": "", - "type": "string" + "type": "string", + "x-codegen-formatPattern": "yyyy-MM-dd'T'HH:mm:ssZ" }, "modifiedBy": { "description": "", @@ -2778,24 +3328,23 @@ "createdOn": "2019-03-22T12:51:19Z" } }, - "ArtifactMetaData": { - "title": "Root Type for ArtifactMetaData", + "VersionMetaData": { + "title": "Root Type for ArtifactVersionMetaData", "description": "", "required": [ - "id", - "createdBy", "createdOn", - "modifiedBy", - "modifiedOn", + "createdBy", "version", "type", "globalId", - "state", - "group", + "id", "contentId" ], "type": "object", "properties": { + "version": { + "type": "string" + }, "name": { "type": "string" }, @@ -2807,22 +3356,8 @@ }, "createdOn": { "format": "utc-date", - "type": "string" - }, - "modifiedBy": { - "type": "string" - }, - "modifiedOn": { - "format": "utc-date", - "type": "string" - }, - "id": { - "$ref": "#/components/schemas/ArtifactId", - "description": "" - }, - "version": { - "description": "", - "type": "string" + "type": "string", + "x-codegen-formatPattern": "yyyy-MM-dd'T'HH:mm:ssZ" }, "type": { "$ref": "#/components/schemas/ArtifactType", @@ -2837,6 +3372,10 @@ "$ref": "#/components/schemas/ArtifactState", "description": "" }, + "id": { + "$ref": "#/components/schemas/ArtifactId", + "description": "" + }, "labels": { "description": "", "type": "array", @@ -2860,17 +3399,15 @@ }, "example": { "groupId": "My-Group", - "id": "Procurement-Invoice", + "id": "my-artifact-id", + "version": 1221432, + "type": "PROTOBUF", "name": "Artifact Name", - "description": "Description of the artifact", - "type": "AVRO", - "version": 18, + "description": "The description of the artifact", "createdBy": "user1", - "createdOn": "2019-03-22T12:51:19Z", - "modifiedBy": "user2", - "modifiedOn": "2019-07-19T15:09:00Z", - "globalId": 12984719247, - "contentId": 82736, + "createdOn": "2019-05-17T12:00:00Z", + "globalId": 183282932983, + "contentId": 12347, "labels": [ "label-1", "label-2" @@ -2878,219 +3415,323 @@ "properties": { "custom-1": "foo", "custom-2": "bar" - } + }, + "references": [ + { + "groupId": "mygroup", + "artifactId": "13842090-2ce3-11ec-8d3d-0242ac130003", + "version": 2, + "name": "foo.bar.Open" + } + ] } }, - "LogConfiguration": { - "description": "", + "SearchedVersion": { + "description": "Models a single artifact from the result set returned when searching for artifacts.", "required": [ - "level" + "createdBy", + "createdOn", + "type", + "state", + "globalId", + "version", + "contentId", + "references" ], "type": "object", "properties": { - "level": { - "$ref": "#/components/schemas/LogLevel", + "name": { + "description": "", + "type": "string" + }, + "description": { + "description": "", + "type": "string" + }, + "createdOn": { + "format": "utc-date", + "description": "", + "type": "string", + "x-codegen-formatPattern": "yyyy-MM-dd'T'HH:mm:ssZ" + }, + "createdBy": { + "description": "", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/ArtifactType", + "description": "" + }, + "labels": { + "description": "", + "type": "array", + "items": { + "type": "string" + } + }, + "state": { + "$ref": "#/components/schemas/ArtifactState", + "description": "" + }, + "globalId": { + "format": "int64", + "description": "", + "type": "integer" + }, + "version": { + "description": "", + "type": "string" + }, + "properties": { + "$ref": "#/components/schemas/Properties", "description": "" + }, + "contentId": { + "format": "int64", + "description": "", + "type": "integer" + }, + "references": { + "description": "", + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtifactReference" + } } + }, + "example": { + "name": "Artifact Version Name", + "description": "Description of the artifact version", + "labels": [ + "current", + "internal" + ], + "type": "AVRO", + "state": "ENABLED", + "createdOn": "2018-02-10T09:30Z", + "createdBy": "some text", + "globalId": 37, + "version": 85, + "properties": {}, + "contentId": 62, + "references": {} } }, - "NamedLogConfiguration": { - "description": "", + "RuleViolationError": { + "title": "Root Type for Error", + "description": "All error responses, whether `4xx` or `5xx` will include one of these as the response\nbody.", "type": "object", "allOf": [ { "required": [ - "name" + "causes" ], "type": "object", "properties": { - "name": { - "description": "", - "type": "string" + "causes": { + "description": "List of rule violation causes.", + "type": "array", + "items": { + "$ref": "#/components/schemas/RuleViolationCause" + } } } }, { - "$ref": "#/components/schemas/LogConfiguration" + "$ref": "#/components/schemas/Error" } - ] - }, - "Properties": { - "description": "User-defined name-value pairs. Name and value must be strings.", - "type": "object", - "additionalProperties": { - "type": "string" - }, - "x-codegen-inline": true, - "x-codegen-type": "StringMap" - }, - "IfExists": { - "description": "", - "enum": [ - "FAIL", - "UPDATE", - "RETURN", - "RETURN_OR_UPDATE" - ], - "type": "string" - }, - "SortBy": { - "description": "", - "enum": [ - "name", - "createdOn" ], - "type": "string" + "example": { + "error_code": 409, + "message": "Artifact failed validation", + "causes": [ + { + "description": "API is missing a title", + "context": "/info[title]" + }, + { + "description": "Operation IDs must be unique", + "context": "/paths[/invoices]/put[operationId]" + } + ] + }, + "x-codegen-extendsClass": "io.apicurio.registry.rest.v2.beans.Error" }, - "LogLevel": { - "description": "", - "enum": [ - "DEBUG", - "TRACE", - "WARN", - "ERROR", - "SEVERE", - "WARNING", - "INFO", - "CONFIG", - "FINE", - "FINER", - "FINEST" + "ArtifactReference": { + "title": "Root Type for ArtifactReference", + "description": "A reference to a different artifact. Typically used with artifact types that can have dependencies like Protobuf.", + "required": [ + "artifactId", + "groupId", + "name" ], - "type": "string", - "x-codegen-package": "io.apicurio.registry.types" - }, - "SystemInfo": { - "title": "Root Type for SystemInfo", - "description": "", "type": "object", "properties": { - "name": { + "groupId": { "type": "string" }, - "description": { + "artifactId": { "type": "string" }, "version": { "type": "string" }, - "builtOn": { - "format": "utc-date", + "name": { "type": "string" } }, "example": { - "name": "Apicurio Registry (SQL)", - "description": "The Apicurio Registry application.", - "version": "2.0.0.Final", - "builtOn": "2021-03-19T12:55:00Z" + "groupId": "mygroup", + "artifactId": "13842090-2ce3-11ec-8d3d-0242ac130003", + "version": "2", + "name": "foo.bar.Open" } }, - "FileContent": { - "format": "binary", - "type": "string", - "x-codegen-inline": true + "ContentCreateRequest": { + "description": "", + "required": [ + "content", + "references" + ], + "type": "object", + "properties": { + "content": { + "description": "Raw content of the artifact.", + "type": "string", + "example": "" + }, + "references": { + "description": "Collection of references to other artifacts.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtifactReference" + } + } + } }, - "RoleMapping": { - "description": "The mapping between a user/principal and their role.", + "ConfigurationProperty": { + "title": "Root Type for ConfigurationProperty", + "description": "", "required": [ - "principalId", - "role" + "name", + "value", + "type", + "label", + "description" ], "type": "object", "properties": { - "principalId": { + "name": { + "type": "string" + }, + "value": { + "type": "string" + }, + "type": { "description": "", "type": "string" }, - "role": { - "$ref": "#/components/schemas/RoleType", - "description": "" + "label": { + "description": "", + "type": "string" + }, + "description": { + "description": "", + "type": "string" } }, "example": { - "principalId": "user1", - "role": "READ_ONLY" + "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." } }, - "RoleType": { - "description": "", - "enum": [ - "READ_ONLY", - "DEVELOPER", - "ADMIN" - ], - "type": "string", - "x-codegen-package": "io.apicurio.registry.types" - }, - "UpdateRole": { - "title": "Root Type for UpdateRole", + "UpdateConfigurationProperty": { + "title": "Root Type for UpdateConfigurationProperty", "description": "", "required": [ - "role" + "value" ], "type": "object", "properties": { - "role": { - "$ref": "#/components/schemas/RoleType" + "value": { + "type": "string" } }, "example": { - "role": "READ_ONLY" + "value": "true" } }, - "UserInfo": { - "title": "Root Type for UserInfo", - "description": "Information about a single user.", + "Limits": { + "title": "Root Type for Limits", + "description": "List of limitations on used resources, that are applied on the current instance of Registry.\nKeys represent the resource type and are suffixed by the corresponding unit.\nValues are integers. Only non-negative values are allowed, with the exception of -1, which means that the limit is not applied.", "type": "object", "properties": { - "username": { - "type": "string" + "maxTotalSchemasCount": { + "format": "int64", + "type": "integer" }, - "displayName": { - "type": "string" + "maxSchemaSizeBytes": { + "format": "int64", + "type": "integer" }, - "admin": { - "type": "boolean" + "maxArtifactsCount": { + "format": "int64", + "type": "integer" }, - "developer": { - "type": "boolean" + "maxVersionsPerArtifactCount": { + "format": "int64", + "type": "integer" }, - "viewer": { - "type": "boolean" + "maxArtifactPropertiesCount": { + "format": "int64", + "type": "integer" + }, + "maxPropertyKeySizeBytes": { + "format": "int64", + "type": "integer" + }, + "maxPropertyValueSizeBytes": { + "format": "int64", + "type": "integer" + }, + "maxArtifactLabelsCount": { + "format": "int64", + "type": "integer" + }, + "maxLabelSizeBytes": { + "format": "int64", + "type": "integer" + }, + "maxArtifactNameLengthChars": { + "format": "int64", + "type": "integer" + }, + "maxArtifactDescriptionLengthChars": { + "format": "int64", + "type": "integer" + }, + "maxRequestsPerSecondCount": { + "format": "int64", + "type": "integer" } }, "example": { - "username": "dprince", - "displayName": "Diana Prince", - "admin": true, - "developer": false, - "viewer": false + "maxTotalSchemasCount": -1, + "maxSchemaSizeBytes": -1, + "maxArtifactsCount": -1, + "maxVersionsPerArtifactCount": -1, + "maxArtifactPropertiesCount": -1, + "maxPropertyKeySizeBytes": -1, + "maxPropertyValueSizeBytes": -1, + "maxArtifactLabelsCount": -1, + "maxLabelSizeBytes": -1, + "maxArtifactNameLengthChars": -1, + "maxArtifactDescriptionLengthChars": -1, + "maxRequestsPerSecondCount": -1 } - }, - "EncodedArtifactName": { - "description": "Base64 encoded name of the artifact.", - "type": "string", - "example": "\"QXJ0aWZhY3QgbmFtZQo=\"", - "x-codegen-inline": true - }, - "EncodedArtifactDescription": { - "description": "Base64 encoded description of the artifact.", - "type": "string", - "example": "\"QXJ0aWZhY3QgZGVzY3JpcHRpb24K\"", - "x-codegen-inline": true - }, - "ArtifactName": { - "description": "Name of the artifact.", - "type": "string", - "example": "\"Artifact name\"", - "x-codegen-inline": true - }, - "ArtifactDescription": { - "description": "Description of the artifact.", - "type": "string", - "example": "\"Artifact description\"", - "x-codegen-inline": true } }, "responses": { @@ -3247,10 +3888,5 @@ "name": "Users", "description": "Some operations related to users." } - ], - "x-codegen": { - "bean-annotations": [ - "io.quarkus.runtime.annotations.RegisterForReflection" - ] - } + ] }