Jira REST API for Remote Issue Links

Available:

Jira 5.0 and later.

This page gives a practical introduction to the Jira Remote Issue Links REST API for app developers. We assume that you know what remote links are and the value they provide. If not, see the overview on Jira Remote Issue Links page.

To use the REST API to manipulate remote links on an issue, you need to authenticate as a user that has the permission to create links on the issue.

There are only two required fields for creating a link to a remote object: a URL and a link title.

1
2
POST http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink

1
2
{
    "object": {
        "url":"http://www.mycompany.com/support?id=1",
        "title":"Crazy customer support issue"
    }
}

The request will give you the successful response:

1
2
{
    "self":"http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink/100",
    "id":100
}

And it will give render simple link in the UI.

To ensure a good user experience (that is, UX), the ability to easily update link information and provide custom link rendering apps in Jira, we suggest that you provide all the recommended fields defined in the guide to the Remote Issue Links fields.

It is possible to customize what is displayed on the Remote Link by providing more information about the link. For a full definition of all the fields, both recommended and optional, see the guide to the Remote Issue Links fields.

Here is another example of request and response:

1
2
POST http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink

1
2
{
    "globalId": "system=http://www.mycompany.com/support&id=1",
    "application": {                                            
         "type":"com.acme.tracker",                      
         "name":"My Acme Tracker"
    },
    "relationship":"causes",                           
    "object": {                                            
        "url":"http://www.mycompany.com/support?id=1",     
        "title":"TSTSUP-111",                             
        "summary":"Crazy customer support issue",        
        "icon": {                                         
            "url16x16":"http://www.openwebgraphics.com/resources/data/3321/16x16_voice-support.png",    
            "title":"Support Ticket"     
        },
        "status": {                                           
            "resolved": true,                                          
            "icon": {                                                       
                "url16x16":"http://www.openwebgraphics.com/resources/data/47/accept.png",
                "title":"Case Closed",                                     
                "link":"http://www.mycompany.com/support?id=1&details=closed"
            }
        }
    }
}

This example will give the same REST response as the earlier example, but it will render the following link in the UI.

If you create a link with the same globalId as an existing Remote Link on an issue, you will update the existing remote link instead of creating a new one. See about updating a Remote Link by global ID later on this page.

When you create a link, you can optionally supply globalId – an identifier that uniquely identifies the remote application and the remote object within the remote system. This globally unique identifier can be used to update or delete existing links on an issue.

1
2
POST http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink

1
2
{
    "globalId": "system=http://www.mycompany.com/support&id=1",                          
    "object": {                                                     
        "url":"http://www.mycompany.com/support?id=1",
        "title":"Crazy customer support issue (RESOLVED)"                        
    }
}

If a remote link on the issue exists with the same URL, the remote link will be updated. Otherwise it will be created.

The update will replace all existing fields with the new values. Fields not present in the request are interpreted as having a null value.

You can also update a Remote Link by referring to the internal ID returned after creation. You can get this ID by sending a GET request for a list of remote links on an issue.

1
2
PUT http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink/100

1
2
{   
    "object": {
        "url":"http://www.mycompany.com/support?id=1",
        "title":"Crazy customer support issue (RESOLVED)"
    }
}

The update will replace all existing fields with the new values. Fields not present in the request are interpreted as having a null value.

This approach can be used to update the globalId on a remote link.

When you create a link, you can optionally supply a globalId – an identifier that uniquely identifies the remote application and the remote object within the remote system. This globally unique identifier can be used to update or delete existing links on an issue. The globalId in the URL should be URL encoded.

1
2
DELETE http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink?globalId=system%3Dhttp%3A%2F%2Fwww.mycompany.com%2Fsupport%26id%3D1

This will result in a 404 if the issue does not have a Remote Link matching the globalId.

You can delete Remote Links by executing a DELETE method on a known Remote Link internal ID:

1
2
DELETE http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink/100

This will result in a 404 if the link does not exist.

You can find all the Remote Links associated with an issue by making a GET on the following resource:

1
2
GET http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink

This will return an array of Remote Links:

1
2
[{
    "id":100,
    "self":"http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink/100",
    "object": {
        "url":"http://www.mycompany.com/support?id=1",
        "title":"Crazy customer support issue (RESOLVED)"    
    }
}]

You can find a Remote Link on an issue by querying by the globalId.

1
2
GET http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink?globalId=system%3Dhttp%3A%2F%2Fwww.mycompany.com%2Fsupport%26id%3D1

You can also find a Remote Link on an issue by entering the "self" URL that specifies the internal ID.

1
2
GET http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink/100

Rate this page: