This manual shows how to interact with the plugin over REST API. Every function of the plugin could be performed with REST also.
All API is also available on 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:
Actual Value depends on Encoded value of your password and username. 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. |
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.
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.
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.
POST http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/ |
Body of the Request should be a JSON document with following structure:
{ "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.
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.
Below you will use sample codes to perform mapping creation using various programming languages:
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); } } } |
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() { /* ... */ }); |
Returns all component and version mapping in the JIRA installation. Includes only projects for which you have BROWSE permission.
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings |
Response will be a JSON document with following format:
[ { "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 } ] |
Updates release date and release flag of an already existing mapping.
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.
{ "released": true, "releaseDate": 1441832400000, "releaseDateStr": "10/Sep/15" } |
Response is a JSON document with updated mapping information.
{ "id": 6, "projectId": 10000, "componentId": 10100, "versionId": 10100, "releaseDate": 1441832400000, "released": true } |
Delete a mapping send a DELETE request to following URL. mappingId is id of the component to version mapping you like to delete.
DELETE http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/{mappingId} |
Returns a previously created component to version mapping using its mapping id.
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/{mappingId} |
Response is a JSON with all the details of mapping.
{ "id":11, "componentId":10100, "versionId":10100, "releaseDate":1441746000000, "released":true } |
Returns a previously created component to version mapping.
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/{componentId}/{versionId} |
Response is a JSON with all the details of mapping.
{ "id":11, "componentId":10100, "versionId":10100, "releaseDate":1441746000000, "released":true } |
Returns list of mappings for the requested component, that is list of valid versions for this component.
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/component/{componentId} |
Response is a JSON with list of mappings.
[ { "id": 1, "projectId": 10000, "componentId": 10000, "versionId": 10000, "releaseDate": 1458770400000, "released": true }, { "id": 2, "projectId": 10000, "componentId": 10000, "versionId": 10001, "released": false } ] |
Returns a list of mappings this version is used. That is list of components for which this version is valid.
GET http://localhost:2990/jira/rest/com.deniz.jira.mapping/latest/mappings/version/{versionId} |
Response is a JSON with list of mappings.
[ { "id": 1, "projectId": 10000, "componentId": 10000, "versionId": 10000, "releaseDate": 1458770400000, "released": true } ] |
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.
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.
[ { "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 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.
Returns all bundles for the requested project.
GET /rest/com.deniz.jira.mapping/latest/bundles?projectKey={projectKey} |
Response is a JSON array of bundles defined for the project.
[ { "id": 3, "versionId": 10005, "projectKey": "ERP", "projectId": 10000, "releaseDate": 1458165600000, "bundleName": "A New Bundle", "releaseDateStr": "17/Mar/16", "released": true } ] |
Returns information about a bundle with requested id. This returns only information on bundle not components containd in the bundle.
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.
{ "id": 3, "versionId": 10005, "projectKey": "ERP", "projectId": 10000, "releaseDate": 1458165600000, "bundleName": "A New Bundle", "releaseDateStr": "17/Mar/16", "released": true } |
Create a new bundle.
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.
{ "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.
{ "id": 3, "versionId": 10005, "projectKey": "ERP", "projectId": 10000, "releaseDate": 1458165600000, "bundleName": "A New Bundle", "releaseDateStr": "17/Mar/16", "released": true } |
Update an existing bundle.
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.
{ "versionId": 10005, "releaseDate": 1458165600000, "bundleName": "New Name", "released": true } |
Response is a JSON document with updated mapping information.
{ "versionId": 10005, "releaseDate": 1458165600000, "bundleName": "New Name", "released": true } |
Delete a bundle.
DELETE /rest/com.deniz.jira.mapping/latest/bundles/{bundleId} |
A Response with code 200 is returned if bundle is succesfully deleted.
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.
{ "bundleId": 3, "componentId": 10000, "versionId": 10000 } |
Response is also a JSON document with created id. You can use this id to remove component from the bundle.
{ "id": 7, "bundleId": 3, "componentId": 10000, "versionId": 10000 } |
Returns all components contained in the bundle with given bundle id.
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.
[ { "id":6, "bundleId":6, "componentId":10000, "versionId":10000, "componentName":"C1", "versionName":"1.0" } ] |
Remove a component release from the bundle with content id.
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 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.
Returns virtual components created for the project
GET /jira/rest/com.deniz.jira.mapping/latest/virtualComponent?projectKey={projectKey}&filterUsedInHierarchy={filterUsedInHierarchy} - projectKey: Key of the project - filterUsedInHierarchy: Default to false. If true it returns virtual components that are not already used inside project hierarchy |
Response is list of virtual components in JSON format.
[ { "name": "Mobile", "projectId": 10000, "id": 1 }, { "name": "Database", "projectId": 10000, "id": 2 }, { "name": "API", "projectId": 10000, "id": 3 } ] |
Creates a new virtual component.
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.
{ "name": "Database", "projectId": 10000, "id": 6 } |
Updates an existing virtual component.
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.
{ "name": "New Name", "projectId": 10000, "id": 6 } |
Delete an existing virtual component.
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.
Returns subcomponent hierarchy of the project with given project key. Returned JSON is compatible with Fancy Tree.
The same method also exist with projectId instead of projectKey. |
GET /rest/com.deniz.jira.mapping/latest/componentHierarchy?projectKey={projectKey} |
Response is a JSON document and compatible with Fancy Tree UI component.
[ { "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 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.
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.
{ "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 a subcomponent from its hierarchy. This does not delete the component, it only removes component from hierarchy.
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.
{ "linkId": 21, "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": [] } |