Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


This manual shows how to interact with the plugin over REST API. Every function of the plugin could be performed with REST also.

Info
titleApiary

All API is also available on moved to Apiary. It is documented using "API Blueprint" syntax. Since apiary is a tool for REST API documentation it allows you more options, for example testing API against your server, or generating source codes for a lot of languages.

 

All of the requests require authentication. You can use Digest Authentication and provide authentication information in the header.

For all request you can set Conent-Type and Authorization information as follows:

Info
titleCommon Headers
Code Block
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4= 

Actual Value depends on Encoded value of your password and username.

StatuscolourRedtitleWARNING Don't Use Basic Authentication Without HTTPS, especially in untrusted environments. Username and password combination can be monitored if someone intercepts the connection between browser and JIRA server. Warning
titleURL Depends on Your Target Environment
In the examples given below, URL

of

the JIRA is http://localhost:2990/jira. You have to replace this with your own server URL. Please note that you may not be using /jira part of above URL.

 

API can be broken into 3 sections. Component Versions, Bundles and Subcomponents. Each of them are grouped into its own section.

Table of Contents
outlinetrue

Component and Version Mappings

Component versions is used to setup mapping between a component and version that indicates this version is valid for that component. Depending on the setting plugin either does not allow other versions to be selected or highlight other versions as invalid.

Creating a New Mapping

You can create a new mapping between a component and version. You need to pass projectId, but future version of the plugin will not need it.

Code Block
POST http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/

Body of the Request should be a JSON document with following structure:

Code Block
{
     "componentId": 10003,
     "versionId": 10001,
     "released": true,
     "releaseDate": 1441746000000
}

Every value is self explanatory. releaseDate is in milliseconds since Epoch according to your JIRA server's time zone.  

Info

In a previous versions of the API you were required to submit projectId but it is not required anymore. Because component ids are unique across projects.

Returned value will also be a JSON document which also contains id of the mapping creating. You can do other operations using this returned id.

...

languages

...

Code Block
languagejava
titleCreating a Mapping With Java Using REST API
collapsetrue
import org.apache.http.client.fluent.*;
import org.apache.http.entity.ContentType;

public class SendRequest {

    public static void main(String[] args) {
        sendRequest();
    }

    private static void sendRequest() {
        // Create New Mapping (POST )
        try {
            // Create request
            Content content = Request.Post("http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/")
                    // Add headers
                    .addHeader("Authorization", "Basic YWRtaW46YWRtaW4=")
                    // Add body
                    .bodyString("{projectId: 10000, componentId: 10003, versionId: 10001, released: true, releaseDate: 1441746000000}", ContentType.DEFAULT_TEXT)
                    // Fetch request and return content
                    .execute().returnContent();
            // Print content
            System.out.println(content);
        } catch (IOException e) {
            System.out.println(e);
        }
    }
}
Code Block
languagejs
titleCreating a Mapping with JQuery Using REST API
collapsetrue
jQuery.ajax({
    url: "http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/",
    type: "POST",
    headers: {
        "Authorization": "Basic YWRtaW46YWRtaW4=",
    },
    processData: false,
    data: "{\
       projectId: 10000,\
       versionId: 10001,\
       componentId: 10003,\
       released: true,\
       releaseDate: 1441746000000\
    }"
}).done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
}).fail(function(jqXHR, textStatus, errorThrown) {
        console.log("HTTP Request Failed");
}).always(function() {
        /* ... */ 
});

Retrieving All Mappings for All Projects

Returns all component and version mapping in the JIRA installation. Includes only projects for which you have BROWSE permission.

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings

Response will be a JSON document with following format:

Code Block
languagejs
[
            {
                "id": 6,
                "projectId": 10000,
                "projectName": "ERP",
                "projectKey": "ERP",
                "componentId": 10100,
                "componentName": "ABC-new",
                "versionId": 10100,
                "versionName": "4.1",
                "releaseDate": 1441746000000,
                "releaseDateStr": "9/Sep/15",
                "released": true
            },
            {
                "id": 4,
                "projectId": 10000,
                "projectName": "ERP",
                "projectKey": "ERP",
                "componentId": 10001,
                "componentName": "C2",
                "versionId": 10002,
                "versionName": "3.0",
                "releaseDate": 1457647200000,
                "releaseDateStr": "11/Mar/16",
                "released": false
            },
            {
                "id": 3,
                "projectId": 10000,
                "projectName": "ERP",
                "projectKey": "ERP",
                "componentId": 10001,
                "componentName": "C2",
                "versionId": 10001,
                "versionName": "2.0",
                "releaseDateStr": "",
                "released": false
            }
        ]

Updating Component to Version Mapping

Updates release date and release flag of an already existing mapping. 

Code Block
PUT http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/{mappingId}
 - mappingId: id of the mapping to be updated

Body of the request should contain new mapping information. You only need to specify either releaseDate or releaseDateStr attribute. If you specify releaseDateStr it should be in the format used by your JIRA instance.

Code Block
{
    "released": true,
    "releaseDate": 1441832400000,
    "releaseDateStr": "10/Sep/15"
}

Response is a JSON document with updated mapping information.

Code Block
{
    "id": 6,
    "projectId": 10000,
    "componentId": 10100,
    "versionId": 10100,
    "releaseDate": 1441832400000,
    "released": true
}

Delete a Component to Version Mapping

Delete a mapping send a DELETE request to following URL. mappingId is id of the component to version mapping you like to delete.

Code Block
DELETE http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/{mappingId}

Get Component to Version Mapping with Mapping Id 

Returns a previously created component to version mapping using its mapping id.

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/{mappingId}

Response is a JSON with all the details of mapping. 

Code Block
{
    "id":11,
    "componentId":10100,
    "versionId":10100,
    "releaseDate":1441746000000,
	"released":true
}

Get Component to Version Mapping with Component and Version Id

Returns a previously created component to version mapping.

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/{componentId}/{versionId}

Response is a JSON with all the details of mapping. 

Code Block
{
	"id":11,
	"componentId":10100,
	"versionId":10100,
	"releaseDate":1441746000000,
	"released":true
}

Get All Mapping for Component 

Returns list of mappings for the requested component, that is list of valid versions for this component.

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/component/{componentId}

Response is a JSON with list of mappings.

Code Block
[
    {
        "id": 1,
        "projectId": 10000,
        "componentId": 10000,
        "versionId": 10000,
        "releaseDate": 1458770400000,
        "released": true
    },
    {
        "id": 2,
        "projectId": 10000,
        "componentId": 10000,
        "versionId": 10001,
        "released": false
    }
]

Get All Mapping for Version

Returns a list of mappings this version is used. That is list of components for which this version is valid.

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/version/{versionId}

Response is a JSON with list of mappings.

Code Block
[
    {
        "id": 1,
        "projectId": 10000,
        "componentId": 10000,
        "versionId": 10000,
        "releaseDate": 1458770400000,
        "released": true
    }
]

Get Applicable Versions

Returns list of JIRA versions (NOT Mappings) which are valid for the requested components. You can repeat selectedComponentIds parameter as many times as you want. List of valid versions are determined using plugin settings (union/intersection of version for each component). If you omit the selectedComponentIds it returns either all versions or only versions defined as bundle versions.

Code Block
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/applicable_versions?selectedComponentIds={componentId}

Response is a JSON document with list of applicable JIRA Project versions.

Code Block
[
    {
        "id": -1,
        "name": "Unknown",
        "description": "Unknown",
        "isReleased": false,
        "sequence": -1,
        "isValid": true
    },
    {
        "id": 10100,
        "name": "4.1",
        "description": "test",
        "releaseDate": 1457474400000,
        "isReleased": true,
        "sequence": 7,
        "isValid": true
    }
]

Bundles

Bundles allows you to group component releases within a project. This effectively creates another higher level grouping and release of components as a group within a project. Using following REST API you can integrate your build process to bundle handling provided by the plugin.

Get All Bundles of a Project 

Returns all bundles for the requested project.

Code Block
GET /rest/com.deniz.jira.mapping/latest/bundles?projectKey={projectKey}

Response is a JSON array of bundles defined for the project.

Code Block
[
    {
        "id": 3,
        "versionId": 10005,
	    "projectKey": "ERP",
        "projectId": 10000,
        "releaseDate": 1458165600000,
        "bundleName": "A New Bundle",
        "releaseDateStr": "17/Mar/16",
        "released": true
    }
]

Get a Bundle with Bundle Id

Returns information about a bundle with requested id. This returns only information on bundle not components containd in the bundle.

Code Block
GET /rest/com.deniz.jira.mapping/latest/bundles/{bundleId}

Response is a JSON document with bundle information. Release date may not be available if bundle is not released.

Code Block
{
    "id": 3,
    "versionId": 10005,
    "projectKey": "ERP",
    "projectId": 10000,
    "releaseDate": 1458165600000,
    "bundleName": "A New Bundle",
    "releaseDateStr": "17/Mar/16",
    "released": true
}

Add a New Bundle

Create a new bundle.

Code Block
POST /rest/com.deniz.jira.mapping/latest/bundles/

You should include bundle information to be included in the request body. You don't need to include releaseDate if bundle is not released.

Code Block
{
   "versionId": 10005,
   "bundleName": "A New Bundle",
   "releaseDate": 1458165600000,
   "released": true
}

Response is a JSON document with created mapping information. Id of bundle can be used for further requests.

Code Block
{
    "id": 3,
    "versionId": 10005,
	"projectKey": "ERP",
    "projectId": 10000,
    "releaseDate": 1458165600000,
    "bundleName": "A New Bundle",
    "releaseDateStr": "17/Mar/16",
    "released": true
}

Update an Existing Bundle

Update an existing bundle.

Code Block
PUT /rest/com.deniz.jira.mapping/latest/bundles/{bundleId}

You should include bundle information to be included in the request body. You don't need to include releaseDate if bundle is not released. Note that this is not additive, it completely overrides existing information for the bundle. For example if you don't include released flag, it is assumed to be false and unreleases the bundle.

Code Block
{
    "versionId": 10005,
    "releaseDate": 1458165600000,
    "bundleName": "New Name",
    "released": true
}

Response is a JSON document with updated mapping information. 

Code Block
{
   "versionId": 10005,
   "releaseDate": 1458165600000,
   "bundleName": "New Name",
   "released": true
}

Delete a Bundle with Bundle Id 

Delete a bundle.

Code Block
DELETE /rest/com.deniz.jira.mapping/latest/bundles/{bundleId}

A Response with code 200 is returned if bundle is succesfully deleted.

 Add a Component Release to Bundle

Code Block
POST /jira/rest/com.deniz.jira.mapping/latest/bundles/components

Information of component and bundle should be send in the body of the request in JSON format.

Code Block
{
   "bundleId": 3,
   "componentId": 10000,
   "versionId": 10000
}

...

.

...

Code Block
{
   "id": 7,
   "bundleId": 3,
   "componentId": 10000,
   "versionId": 10000
}

...

Returns all components contained in the bundle with given bundle id. 

Code Block
GET /rest/com.deniz.jira.mapping/latest/bundles/components?bundleId={bundleId}

Response is array of components and their corresponding versions contained in the bundle in JSON format.

Code Block
[
   {
      "id":6,
      "bundleId":6,
      "componentId":10000,
      "versionId":10000,
      "componentName":"C1",
      "versionName":"1.0"
   }
]

Remove a Component Release from a Bundle

Remove a component release from the bundle with content id. 

Code Block
DELETE /rest/com.deniz.jira.mapping/latest/bundles/components/{id}

A Response with code 200 is returned if component release is succesfully removed from the bundle.

POST /jira/rest/com.deniz.jira.mapping/latest/bundles/components

 

Subcomponents

Subcomponents allows you to group create hierarchy of components with parent child relationships. In addition to usual project components you can also create virtual components, which are not actual JIRA components but only exist to group components.

Get All Virtual Components of a Project

Returns virtual components created for the project

...

 

...

Response is list of virtual components in JSON format.

Code Block
[
    {
        "name": "Mobile",
        "projectId": 10000,
        "id": 1
    },
    {
        "name": "Database",
        "projectId": 10000,
        "id": 2
    },
    {
        "name": "API",
        "projectId": 10000,
        "id": 3
    }
]

Add a New Virtual Component

Creates a new virtual component.

Code Block
POST /jira/rest/com.deniz.jira.mapping/latest/virtualComponent?projectKey={projectKey}&name={name}
- projectKey: project key
- name: name of virtual component. It should be unique inside the project 

Response is a JSON document with new virtual component id. You can use that id to perform further requests.

Code Block
{
    "name": "Database",
    "projectId": 10000,
    "id": 6
}

Update an Existing Virtual Component 

Updates an existing virtual component.

Code Block
POST /jira/rest/com.deniz.jira.mapping/latest/virtualComponent/{virtualComponentId}?name={name}
- virtualComponentId: id of virtual component to be updated
- name: new name of virtual component

Response is a JSON document with updated virtual component information.

Code Block
{
    "name": "New Name",
    "projectId": 10000,
    "id": 6
}

Delete an Existing Virtual Component

Delete an existing virtual component.

Code Block
DELETE /jira/rest/com.deniz.jira.mapping/latest/virtualComponent/{virtualComponentId}
- virtualComponentId: id of virtual component to be deleted.

If virtual component is successfully deleted an empty response with status code 200 is returned.

Get Subcomponent Hierarchy with Project Key

Returns subcomponent hierarchy of the project with given project key. Returned JSON is compatible with Fancy Tree.

Info

The same method also exist with projectId instead of projectKey.

Code Block
GET /rest/com.deniz.jira.mapping/latest/componentHierarchy?projectKey={projectKey}

Response is a JSON document and compatible with Fancy Tree UI component.

Code Block
[
    {
        "linkId": -1,
        "componentId": -1,
        "isVirtual": false,
        "name": "ERP",
        "title": "<img src=\"http://localhost:2990/jira/secure/projectavatar?size=xsmall&avatarId=10324\" class=\"aui-avatar aui-avatar-xsmall aui-avatar-project jira-system-avatar\"><span style=line-height:16px;margin-left:4px>ERP</span>",
        "folder": true,
        "expanded": true,
        "children": [
            {
                "linkId": 11,
                "componentId": 2,
                "isVirtual": true,
                "name": "Database",
                "title": "<span class='aui-icon aui-icon-small aui-iconfont-devtools-folder-open cbsv-component-icon'></span>Database",
                "folder": true,
                "expanded": true,
                "children": [
                    {
                        "linkId": 14,
                        "componentId": 10001,
                        "isVirtual": false,
                        "name": "C2",
                        "title": "<span class='aui-icon aui-icon-small aui-iconfont-component cbsv-component-icon'></span>C2",
                        "folder": false,
                        "expanded": false,
                        "children": []
                    }
                ]
            },
            {
                "linkId": 18,
                "componentId": 3,
                "isVirtual": true,
                "name": "API",
                "title": "<span class='aui-icon aui-icon-small aui-iconfont-devtools-folder-open cbsv-component-icon'></span>API",
                "folder": true,
                "expanded": true,
                "children": [
                    {
                        "linkId": 19,
                        "componentId": 10002,
                        "isVirtual": false,
                        "name": "C3",
                        "title": "<span class='aui-icon aui-icon-small aui-iconfont-component cbsv-component-icon'></span>C3",
                        "folder": false,
                        "expanded": false,
                        "children": []
                    },
                    {
                        "linkId": 20,
                        "componentId": 10000,
                        "isVirtual": false,
                        "name": "C1",
                        "title": "<span class='aui-icon aui-icon-small aui-iconfont-component cbsv-component-icon'></span>C1",
                        "folder": false,
                        "expanded": false,
                        "children": []
                    }
                ]
            }
        ]
    }
]

 Add Subcomponent to Hierarchy 

Add an existing subcomponent (project component or virtual component) to project. Since in theory a virtual component and a project component may have the same id you also need to pass virtual flag both for parent component and subcomponent itself.

Code Block
POST /rest/com.deniz.jira.mapping/latest/componentHierarchy?projectKey=ERP&parentComponentId={parentComponentId}&isParentVirtual={isParentVirtual}&componentId={componentId}&isVirtual={isVirtual}
- projectKey: project key
- parentComponentId: Parent component id, that is the component that will be the parent of the component we are adding to the hierarchy. It may be either a project component or a virtual component
- isParentVirtual: if parent is a project component pass false, if parent is a virtual component pass true
- componentId: id of the component that will be added to hierarchy
- isVirtual: pass true for virtual component, pass false for project component

Response is a JSON document with extra information. Use returned linkId to remove component and all of its children from the hierarchy.

Code Block
{
    "linkId": 22,
    "componentId": 10200,
    "isVirtual": false,
    "name": "c5",
    "title": "<span class='aui-icon aui-icon-small aui-iconfont-component cbsv-component-icon'></span>c5",
    "folder": false,
    "expanded": false,
    "children": []
}

Delete Subcomponent from Hierarchy with Link Id

Delete a subcomponent from its hierarchy. This does not delete the component, it only removes component from hierarchy.

Code Block
DELETE /jira/rest/com.deniz.jira.mapping/latest/componentHierarchy?linkId={linkId}
- linkId (number) - Id when returned a subcomponent is added to hierarch

Response is a JSON document with information of deleted subcomponent.

...