// 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"]
Some {registry} artifact types can include _artifact references_ from one artifact file to another. You can create efficiencies by defining reusable schema or API artifacts, and then referencing them from multiple locations in artifact references. 

The following artifact types support artifact references: 

* Apache Avro 
* Google Protobuf 
* JSON Schema 
* OpenAPI
* AsyncAPI

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"}]
----

.Dereference artifact content

There are some cases where returning artifact content with referenced content inline might be helpful. For these cases, the Core Registry API v2 supports the `dereference` query parameter in certain operations. 

This support is currently implemented only for Avro, Protobuf, OpenAPI, AsyncAPI, and JSON Schema artifacts when the `dereference` parameter is specified in the API operation. This parameter is not supported for any other artifact types.

NOTE: For Protobuf artifacts, dereferencing content is supported only when all the schemas belong to the same package.

NOTE: Circular dependencies are allowed by some artifact types (e.g. JSON Schema) but are not supported by {registry}.

[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}.