// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_managing-registry-artifacts-api.adoc

[id="managing-artifact-versions-using-rest-api_{context}"]
= Managing schema and API artifact versions using {registry} REST API commands

[role="_abstract"]
If you do not specify an artifact version number when adding schema and API artifacts using the Core Registry API v3, {registry} generates a version number automatically. The default version when creating a new artifact is `1`.

{registry} also supports custom versioning where you can specify a version number when creating the artifact or artifact version.  Specifying a custom version value overrides the default version normally assigned when creating an artifact or artifact version. You can then use this version value when executing REST API operations that require a version number.

This section shows a simple curl-based example of using the Core Registry API v3 to add and retrieve a custom Apache Avro schema version in {registry}. You can specify custom version numbers to create artifacts, or to add artifact versions.

.Prerequisites

* {registry} is installed and running in your environment.

.Procedure

. Add an artifact version in the registry using the `/groups/\{groupId\}/artifacts` operation. The following example `curl` command adds a simple artifact for a share price application:
+
[source,bash]
----
$ curl -X POST MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-raw '{
    "artifactId": "my-share-price",
    "artifactType": "AVRO",
    "firstVersion": {
        "version": "1.1.1",
        "content": {
            "content": "{\"type\":\"record\",\"name\":\" p\",\"namespace\":\"com.example\", \"fields\":[{\"name\":\"symbol\",\"type\":\"string\"},{\"name\":\"price\",\"type\":\"string\"}]}",
            "contentType": "application/json"
        }
    }
}'
----
+
* This example adds an Avro schema artifact with an artifact ID of `my-share-price` and version of `1.1.1`. If you do not specify a version, {registry} automatically generates a default version of `1`. 
* `MY-REGISTRY-URL` is the  
ifdef::apicurio-registry[]
host name on which {registry} is deployed. For example: `\http://localhost:8080`.
endif::[]
ifdef::rh-service-registry[]
host name on which {registry} is deployed. For example: `my-cluster-service-registry-myproject.example.com`. 
endif::[]
* This example specifies a group ID of `my-group` in the API path. If you do not specify a unique group ID, you must specify `../groups/default` in the API path.

. Verify that the response includes the expected JSON body to confirm that the custom artifact version was added. For example:
+
[source,bash]
----
{"artifact":{"owner":"","createdOn":"2024-09-26T17:06:21Z","modifiedBy":"","modifiedOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","groupId":"my-group","artifactId":"my-share-price"},"version":{"version":"1.1.1","owner":"","createdOn":"2024-09-26T17:06:21Z","artifactType":"AVRO","globalId":4,"state":"ENABLED","groupId":"my-group","contentId":4,"artifactId":"my-share-price"}}
----
* A custom version of `1.1.1` was specified when adding the artifact.
* This was the fourth artifact added to the registry, so the global ID and content ID have a value of `4`.

. Retrieve the artifact content from the registry using its artifact ID and version in the API path. In this example, the specified ID is `my-share-price` and the version is `1.1.1`:
+
[source,bash]
----
$ curl -H "Authorization: Bearer $ACCESS_TOKEN" \ 
    MY-REGISTRY-URL/apis/registry/v3/groups/my-group/artifacts/my-share-price/versions/1.1.1/content
{"type":"record","name":"price","namespace":"com.example", 
  "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}
----

[role="_additional-resources"]
.Additional resources
* For more details, see the {registry-rest-api}.
