Add Link through API

[Amerehei]

in the Bluescape workspace we have a “Add link” option for texts. I couldn’t find it in the RESTful or GraphQL API. How can I add link using API?

[kkoechley]

You can add a link from an element to another using element traits metadata.

The appLink format is:
https://client.apps.us.bluescape.com/applink/<yourWorkspaceId>?objectId=<objectToLinkTo>

You can set traits to create an appLink using the following format, using traits vocab and content.link:

traits:{
  vocab: "http://bluescape.dev/hyperlinks/v1/", 
    content: {
        link: "#64c01b747b56b021723c62f8"
    }
}

You can either use this to create an element, or you can use updateTraits to update an existing element. These can be done with either REST or graphQL APIs.

A graphQL example of creating a new shape with an appLink linked to another element:

#create shape with json-ld traits data
mutation createShapeWithLinkTraits($ws: String! $x:Float! $y:Float!, $width:Float!, $height:Float!, $textContent:String!) {
        shape1:createShape(
        workspaceId: $ws
            input: {
                text:$textContent
                traits:{
                    vocab: "http://bluescape.dev/hyperlinks/v1/", 
                    content: {
                        link: "#64c01b747b56b021723c62f8"
                    }
                }
                
                mirrorY: false 
                style: {
                    regularShape:{

                        kind:Rectangle
                        width:$width height:$height strokeWidth: 5 
                        #fillColor not working in beta1
                        fillColor: {r:255 g:34 b:255 a:1}
                        strokeColor:{r:0 g:255 b:0 a:1}
                    }   
                }
                transform:{x:$x y:$y}
                textStyle:{
                    fontSize:12
                    verticalAlign:bottom
                    color:{
                        r:0
                        g:0
                        b:255
                        a:1
                    }
                }
            })

        #return values:
        {id kind mirrorY traits}
    }

with variables:

{
    "ws": "{{workspaceID}}",
    "textContent" : "graphQL shape with simple traits",
    "x": 0,
    "y": 0,
    "width": 800,
    "height": 300
}

Or you can use updateTraits to update traits for an existing element:

#update element JSON-LD traits metadata
mutation updateTraitsForLink ($workspaceId:String!, $id:String!, $linkToId:String!){
  updateTraits(workspaceId: $workspaceId id:$id input: {
    vocab: "http://bluescape.dev/hyperlinks/v1/"
    content: {
      link: $linkToId
    }
  })
}

with variables:

{
    "workspaceId": "{{workspaceID}}",
    "id" : "64c031db65246380966440a3",
    "linkToId":"#64c01b747b56b021723c62f8"
}