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

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

[role="_abstract"]
{registry} artifact types such as Apache Avro, Protobuf, and JSON Schema can include _artifact references_ from one artifact file to another. You can create efficiencies by defining reusable schema and API artifacts, and then referencing them from multiple locations.

This section shows a simple curl-based example of using the Core Registry API v2 to add and retrieve an artifact reference to a simple Avro schema artifact in {registry}. 

This example first creates a schema artifact named `ItemId`:

.ItemId schema
[source,json]
---- 
{
    "namespace":"com.example.common",
    "name":"ItemId",
    "type":"record",
    "fields":[
        {
            "name":"id",
            "type":"int"
        }
    ]
}
----

This example then creates a schema artifact named `Item`, which includes a reference to the nested `ItemId` artifact.

.Item schema with nested ItemId schema
[source,json]
---- 
{
    "namespace":"com.example.common",
    "name":"Item",
    "type":"record",
    "fields":[
        {
            "name":"itemId",
            "type":"com.example.common.ItemId"
        },
    ]
}
----

.Prerequisites

ifdef::apicurio-registry,rh-service-registry[]
* {registry} is installed and running in your environment.
endif::[]
ifdef::rh-openshift-sr[]
* You have a service account with the correct access permissions for {registry} instances.
* You have created an access token using your service account credentials. 
* You have logged in to the {registry-url}[{registry} web console]. 
endif::[]

.Procedure
ifdef::rh-openshift-sr[]
. In the {registry} web console, for the {registry} instance that you want to connect to, select the options icon (three vertical dots) and click *Connection*.
. In the *Connection* page, copy the URL for the *Core Registry API* to a secure location. You will use this API endpoint to connect to the {registry} instance. 
endif::[]

. Add the `ItemId` schema artifact that you want to create the nested artifact reference to using the `/groups/\{group\}/artifacts` operation:
+
[source,bash]
----
$ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \
   -H "Content-Type: application/json; artifactType=AVRO" \
   -H "X-Registry-ArtifactId: ItemId" \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   --data '{"namespace": "com.example.common", "type": "record", "name": "ItemId", "fields":[{"name":"id", "type":"int"}]}'      
----
+
* This example adds an Avro schema artifact with an artifact ID of `ItemId`. If you do not specify a unique artifact ID, {registry} generates one automatically as a UUID. 
* `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::[]
ifdef::rh-openshift-sr[]
Core Registry API endpoint that you copied to connect to this {registry} instance. For example: `\https://service-registry.apps.app-sre-0.k3s7.p1.openshiftapps.com/t/f301375a-18a7-426c-bbd8-8e626a0a1d0e`. 
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 artifact was added. For example:
+
[source,bash]
----
{"name":"ItemId","createdBy":"","createdOn":"2022-04-14T10:50:09+0000","modifiedBy":"","modifiedOn":"2022-04-14T10:50:09+0000","id":"ItemId","version":"1","type":"AVRO","globalId":1,"state":"ENABLED","groupId":"my-group","contentId":1,"references":[]}
---- 

. Add the `Item` schema artifact that includes the artifact reference to the `ItemId` schema using the `/groups/\{group\}/artifacts` operation:
+
[source,bash]
----
$ curl -X POST MY-REGISTRY-URL/apis/registry/v2/groups/my-group/artifacts \
-H 'Content-Type: application/create.extended+json' \
-H "X-Registry-ArtifactId: Item" \
-H 'X-Registry-ArtifactType: AVRO' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data-raw '{
    "content": "{\r\n \"namespace\":\"com.example.common\",\r\n  \"name\":\"Item\",\r\n  \"type\":\"record\",\r\n  \"fields\":[\r\n   {\r\n  \"name\":\"itemId\",\r\n   \"type\":\"com.example.common.ItemId\"\r\n        }\r\n    ]\r\n}",
    "references": [
        {
            "groupId": "my-group",
            "artifactId": "ItemId",
            "name": "com.example.common.ItemId",
            "version": "1"
        }
    ]
}'
----
+
* For artifact references, you must specify the custom content type of `application/create.extended+json`, which extends the `application/json` content type. 

. Verify that the response includes the expected JSON body to confirm that the artifact was created with the reference. For example:
+
[source,bash]
----
{"name":"Item","createdBy":"","createdOn":"2022-04-14T11:52:15+0000","modifiedBy":"","modifiedOn":"2022-04-14T11:52:15+0000","id":"Item","version":"1","type":"AVRO","globalId":2,"state":"ENABLED","groupId":"my-group","contentId":2, "references":[{"artifactId":"ItemId","groupId":"my-group","name":"ItemId","version":"1"}] }
----

. Retrieve the artifact reference from {registry} by specifying the global ID of the artifact that includes the reference. In this example, the specified global ID is `2`:
+
[source,bash]
----
$ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/registry/v2/ids/globalIds/2/references  
----

. Verify that the response includes the expected JSON body for this artifact reference. For example:
+
[source,bash]
----
[{"groupId":"my-group","artifactId":"ItemId","version":"1","name":"com.example.common.ItemId"}]
----

[role="_additional-resources"]
.Additional resources
* For more details, see the {registry-rest-api}.
* For more examples of artifact references, see the section on configuring each artifact type in {registry-client-serdes-config}.