Skip to content

How to use the Collection API / CollectionServiceClient

Introduction

Collections are the second-level (and therefore optional) resource to organize stored data i.e. Objects in Projects. Before you can create Collections you need to create a Project in Aruna.

If you don't know how to create a Project you should read the previous chapter about the Project API basics.

Create Collection

API example for creating a new Collection.

Required permissions

This request requires at least APPEND permission on the Project in which the Collection is to be created.

Collection naming guidelines

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Native JSON request to create a simple Collection
curl -d '
  {
    "name": "json-api-collection", 
    "title": "JSON API Collection"
    "description": "Created with JSON over HTTP.",
    "keyValues": [],
    "relations": [],
    "data_class": "DATA_CLASS_PUBLIC",
    "projectId": "<project-id>",
    "metadataLicenseTag": "CC-BY-4.0",
    "defaultDataLicenseTag": "CC-BY-4.0",
    "authors": []
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X POST https://<URL-to-Aruna-instance-API-endpoint>/v2/collections

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Create tonic/ArunaAPI request to create a Collection
let request = CreateCollectionRequest {
    name: "rust-api-collection".to_string(),
    title: "Rust API Collection".to_string(),
    description: "Created with the gRPC Rust API client.".to_string(),
    key_values: vec![],
    relations: vec![],
    data_class: DataClass::Public as i32,
    metadata_license_tag: Some("CC-BY-4.0".to_string()),
    default_data_license_tag: Some("CC-BY-4.0".to_string()),
    parent: Some(Parent::ProjectId("<project-id>".to_string())),
    authors: vec![],
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.create_collection(request)
                             .await
                             .unwrap() 
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# Create tonic/ArunaAPI request to create a new Collection
request = CreateCollectionRequest(
    name="python-api-collection",
    description="Created with the gRPC Python API client.",
    key_values=[], 
    relations=[], 
    data_class=DataClass.DATA_CLASS_PUBLIC,
    project_id="<project-id>",
    metadata_license_tag="CC-BY-4.0",
    default_data_license_tag="CC-BY-4.0",
    authors=[]
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.CreateCollection(request=request)

# Do something with the response
print(f'{response}')

Get Collection(s)

API examples of how to fetch information for one or multiple existing Collections.

Required permissions

This request requires at least READ permissions on the Collection or a parent Project

1
2
3
4
# Native JSON request to fetch information of a collection
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}

1
2
3
4
# Native JSON request to fetch information of multiple Collections
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET 'https://<URL-to-Aruna-instance-API-endpoint>/v2/collections?collectionIds={collection-id-01}&collectionIds={collection-id-02}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Create tonic/ArunaAPI request to fetch information of a collection
let request = GetCollectionRequest {
    collection_id: "<collection-id>".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.get_collection(request)
                                .await
                                .unwrap()
                                .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// Create tonic/ArunaAPI request to fetch information of multiple Collections
let request = GetCollectionsRequest {
    collection_ids: vec![
        "<collection-id-01>".to_string(),
        "<collection-id-02>".to_string(),
        "<...>".to_string(),
    ],
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.get_collections(request)
                                .await
                                .unwrap()
                                .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to fetch information of a Collection
request = GetCollectionRequest(
    collection_id="<collection-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.GetCollection(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Create tonic/ArunaAPI request to fetch information of multiple Collections
request = GetCollectionsRequest(
    collection_ids=[
        "<collection-id-01>",
        "<collection-id-02>",
        "<...>"]
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.GetCollections(request=request)

# Do something with the response
print(f'{response}')

Update Collection

API examples of how to update individual metadata of an existing Collection.

Required permissions
  • Name update needs at least WRITE permissions on the specific Collection or a parent Project
  • Description update needs at least WRITE permissions on the specific Collection or a parent Project
  • KeyValue update needs at least WRITE permissions on the specific Collection or a parent Project
  • Dataclass update needs at least WRITE permissions on the specific Collection or a parent Project
  • License update needs at least WRITE permissions on the specific Collection or a parent Project
1
2
3
4
5
6
7
8
# Native JSON request to update the name of a Collection
curl -d '
  {
    "name": "updated-json-api-collection"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/name

1
2
3
4
5
6
7
8
# Native JSON request to update the title of a Collection
curl -d '
  {
    "name": "Updated JSON API Collection"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/title

1
2
3
4
5
6
7
8
# Native JSON request to update the description of a Collection
curl -d '
  {
    "description": "Updated with JSON over HTTP."
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/description

1
2
3
4
5
6
7
8
9
# Native JSON request to update the key-values associated with a Collection
curl -d '
  {
    "addKeyValues": [],
    "removeKeyValues": []
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/key_values

Info

Dataclass can only be relaxed: Confidential > Workspace > Private > Public

1
2
3
4
5
6
7
8
# Native JSON request to update the dataclass of a Collection
curl -d '
  {
    "dataClass": "DATA_CLASS_PUBLIC"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/data_class

1
2
3
4
5
6
7
8
9
# Native JSON request to update the license of a Collection
curl -d '
  {
    "metadataLicenseTag": "CC0",
    "defaultDataLicenseTag": "CC0"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/licenses

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Native JSON request to add an author to a Collection
curl -d '
  {
    "addAuthors": [
        {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "orcid": "0000-0002-1825-0097",
        "id": "<user-id-if-registered>"
        }
    ],
    "removeAuthors": []
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/authors

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to update the name of a Collection
let request = UpdateCollectionNameRequest {
    collection_id: "<collection-id>".to_string(),
    name: "updated-rust-api-collection".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.update_collection_name(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to update the title of a Collection
let request = UpdateCollectionTitleRequest {
    collection_id: "<collection-id>".to_string(),
    title: "Updated Rust API Collection".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.update_collection_title(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to update the description of a Collection
let request = UpdateCollectionDescriptionRequest {
    collection_id: "<collection-id>".to_string(),
    description: "Updated with the gRPC Rust API client.".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.update_collection_description(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Create tonic/ArunaAPI request to update the key-values associated with a Collection
let request = UpdateCollectionKeyValuesRequest {
    collection_id: "<collection-id>".to_string(),
    add_key_values: vec![], 
    remove_key_values: vec![]
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.update_collection_key_values(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

Info

Dataclass can only be relaxed: Confidential > Private > Public

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to update the datacalass of a Collection
let request = UpdateCollectionDataClassRequest {
    collection_id: "<collection-id>".to_string(),
    data_class: DataClass::Public as i32,
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.update_collection_data_class(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Create tonic/ArunaAPI request to update the license of a Collection
let request = UpdateCollectionLicensesRequest {
    collection_id: "<collection-id>".to_string(),
    metadata_license_tag: "CC0".to_string(),
    default_data_license_tag: "CC0".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.update_collection_licenses(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// Create tonic/ArunaAPI request to add an author to a Collection
let request = UpdateCollectionAuthorsRequest {
    collection_id: "<collection-id>".to_string(),
    add_authors: vec![Author {
        first_name: "John".to_string(),
        last_name: "Doe".to_string(),
        email: "john.doe@example.com".to_string(),
        orcid: "0000-0002-1825-0097".to_string(),
        id: "<user-id-if-registered>".to_string(),
    }],
    remove_authors: vec![],
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.update_collection_authors(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to update the name of a Collection
request = UpdateCollectionNameRequest(
    collection_id="<collection-id>",
    name="updated-python-api-collection"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.UpdateCollectionName(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to update the title of a Collection
request = UpdateCollectionTitleRequest(
    collection_id="<collection-id>",
    title="Updated Python API Collection"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.UpdateCollectionTitle(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to update the description of a Collection
request = UpdateCollectionDescriptionRequest(
    collection_id="<collection-id>",
    description="Updated with the gRPC Python API client"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.UpdateCollectionDescription(request=request)

# Do something with the response
print(f'{response}')

Warning

Removal of KeyValues always triggers the creation of a new object revision.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Create tonic/ArunaAPI request to update the key-values associated with a Collection
request = UpdateCollectionKeyValuesRequest(
    collection_id="<collection-id>",
    add_key_values=[],
    remove_key_values=[]
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.UpdateCollectionKeyValues(request=request)

# Do something with the response
print(f'{response}')

Info

Dataclass can only be relaxed: Confidential > Private > Public

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to relax the data_class of a Collection
request = UpdateCollectionDescriptionRequest(
    collection_id="<collection-id>",
    data_class=DataClass.DATA_CLASS_PUBLIC
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.UpdateCollectionDataClass(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Create tonic/ArunaAPI request to update the licenses of a Collection
request = UpdateCollectionLicensesRequest(
    collection_id="<collection-id>",
    metadata_license_tag="CC0",
    default_data_license_tag="CC0"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.UpdateCollectionLicenses(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# Create tonic/ArunaAPI request to add an author to a Collection
request = UpdateCollectionAuthorsRequest(
    collection_id="<collection-id>",
    add_authors=[Author(
        first_name="John",
        last_name="Doe",
        email="john.doe@example.com",
        orcid="0000-0002-1825-0097",
        user_id="<user-id-if-registered"
    )],
    remove_authors=[]
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.UpdateCollectionAuthors(request=request)

# Do something with the response
print(f'{response}')

Snapshot Collection

API examples of how to snapshot a Collection, i.e. create an immutable clone of the Collection and its underlying resources.

Required permissions

This request requires at least ADMIN permissions on the Collection or the Project under which the collection is registered.

1
2
3
4
# Native JSON request request to snapshot a Collection
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
  -H 'Content-Type: application/json' \
  -X POST https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}/snapshot

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Create tonic/ArunaAPI request to snapshot a Collection
let request = SnapshotCollectionRequest {
    collection_id: "<collection-id>".to_string()
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.snapshot_collection_version(request)
                                .await
                                .unwrap()
                                .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to snapshot a Collection
request = SnapshotCollectionRequest(
    collection_id="<collection-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.SnapshotCollectionVersion(request=request)

# Do something with the response
print(f'{response}')

Delete Collection

API examples of how to delete a Collection.

Info

Deletion does not remove the Collection from the database, but sets the status of the Collection and the underlying resources to "DELETED".

Required permissions

This request requires at least ADMIN permissions on the Collection or the Project under which the collection is registered.

1
2
3
4
# Native JSON request to delete a Collection
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X DELETE https://<URL-to-Aruna-instance-API-endpoint>/v2/collections/{collection-id}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Create tonic/ArunaAPI request to delete a Collection
let request = DeleteCollectionRequest {
    collection_id: "<collection-id>".to_string()
};

// Send the request to the Aruna instance gRPC endpoint
let response = collection_client.delete_collection(request)
                                .await
                                .unwrap()
                                .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to delete a collection
request = DeleteCollectionRequest(
    collection_id="<collection-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.collection_client.DeleteCollection(request=request)

# Do something with the response
print(f'{response}')