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 plugin developers. We assume that you know what remote links are and the value they provide. If not, see the overview in Guide - JIRA Remote Issue Links.

On this page:

In order to use the REST API to manipulate remote links on an issue, you will 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.

POST http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink
{ 
    "object": { 
        "url":"http://www.mycompany.com/support?id=1", 
        "title":"Crazy customer support issue"
    } 
}

Will give you the successful response:

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

And will give render simple link in the UI:

In order to ensure a good user experience (UX), the ability to easily update link information and provide custom link rendering plugins 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 customise 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:

POST http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink
{
    "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 will render the following link in the UI:

Note: 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 below.

When you create a link, you can optionally supply globalId: an identifier which 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.

POST http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink
{
    "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 GETing the list of remote links on an issue.

PUT 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)"
    }
}

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 which 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.

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:

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:

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

This will return an array of remote links:

[{
    "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.

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.

GET http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink/100
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport