links

API endpoint base: https://pirca.arvadosapi.com/arvados/v1/links

Object type: o0j2j

Example UUID: zzzzz-o0j2j-0123456789abcde

Resource

Links are an extensible way to describe relationships between Arvados objects and metadata about individual objects.

Each link has, in addition to the Common resource fields:

Attribute	Type	Description
head_uuid	string	The object being described or acted on.
tail_uuid	string	The origin or actor in the description or action (may be null).
link_class	string	Type of link
name	string	Primary value of the link.
properties	hash	Additional information, expressed as a key→value hash. Key: string. Value: string, number, array, or hash. May be used in queries using subproperty filters

Link classes

Some classes are pre-defined by convention and have standard meanings attached to names.

permission

The significance of permission links is discussed in the permission links section of the permission model documentation.

star

A star link is a shortcut to a project that is displayed in the user interface (Workbench) as “favorites”. Users can mark their own favorites (implemented by creating or deleting star links).

An admin can also create star links owned by the “Public favorites” project. These are favorites will be displayed to all users that have permission to read the project that has been favorited.

The schema for a star link is:

Field	Value	Description
owner_uuid	user or group uuid	Either the user that owns the favorite, or the “Public favorites” group.
tail_uuid	user or group uuid	Should be the same as owner_uuid
head_uuid	project uuid	The project being favorited
link_class	string of value “star”	Indicates this represents a link to a user favorite

Creating a public favorite

owner_uuid is either an individual user, or the “Public favorites” group. The head_uuid is the project being favorited.

$ linkuuid=$(arv --format=uuid link create --link '{
    "link_class": "star",
    "owner_uuid": "zzzzz-j7d0g-publicfavorites",
    "tail_uuid": "zzzzz-j7d0g-publicfavorites",
    "head_uuid":  "zzzzz-j7d0g-theprojectuuid"}')

Removing a favorite

$ arv link delete --uuid zzzzz-o0j2j-thestarlinkuuid

Listing favorites

To list all ‘star’ links that will be displayed for a user:

$ arv link list --filters '[
  ["link_class", "=", "star"],
  ["tail_uuid", "in", ["zzzzz-j7d0g-publicfavorites", "zzzzz-tpzed-currentuseruuid"]]]'

tag

A tag link describes an object using an unparsed plain text string. Tags can be used to annotate objects that are not directly editable by the user, like collections and objects shared as read-only.

tail_type→head_type	name→head_uuid {properties}
→Collection	tag name → collection uuid
→Job	tag name → job uuid

Methods

See Common resource methods for more information about create, delete, get, list, and update.

Required arguments are displayed in green.

create

Create a new Link.

Arguments:

Argument	Type	Description	Location	Example
link	object		query

When you create a new permission link with the same head_uuid and tail_uuid as an existing permission link, the API returns the existing link instead of creating a new one. If the requested permission level is higher than the existing link, the existing link is updated accordingly. Otherwise the existing link is returned unchanged.

delete

Delete an existing Link.

Arguments:

Argument	Type	Description	Location	Example
uuid	string	The UUID of the Link in question.	path

When you delete a permission link, any other existing permission links that have the same head_uuid and tail_uuid are also deleted.

get

Gets a Link’s metadata by UUID.

Arguments:

Argument	Type	Description	Location	Example
uuid	string	The UUID of the Link in question.	path

list

List links.

See common resource list method.

update

Update attributes of an existing Link.

Arguments:

Argument	Type	Description	Location	Example
uuid	string	The UUID of the Link in question.	path
link	object		query

When you update a permission link such that it has the same head_uuid and tail_uuid as one or more existing permission links, the API deletes the other links. If the highest permission level among the deleted links was higher than the newly updated link, the updated link’s permission level is increased accordingly.

get_permissions

Get all permission links that point directly to given UUID (in the head_uuid field). The requesting user must have can_manage permission or be an admin.

Arguments:

Argument	Type	Description	Location	Example
uuid	string	The UUID of the object.	path

---

Previous: keep_services Next: logs