This manual shows how to interact with the plugin over REST API. Every function of the plugin could be performed with REST also.
| Info | ||
|---|---|---|
| ||
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.
...
| title | Common Headers |
|---|
For all request you can set Conent-Type and Authorization information as follows:
| Code Block |
|---|
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4= |
Actual Value depends on Encoded value of your password and username.
...
| Warning | ||
|---|---|---|
| ||
| 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 | ||
|---|---|---|
|
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.
Below you will use sample codes to perform mapping creation using various programming languages:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
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 | ||||||
|---|---|---|---|---|---|---|
| ||||||
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 | ||
|---|---|---|
| ||
[
{
"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
} |
Response is also a JSON document with created id. You can use this id to remove component from the bundle.
| Code Block |
|---|
{
"id": 7,
"bundleId": 3,
"componentId": 10000,
"versionId": 10000
} |
Get Content of a Bundle with Bundle Id
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
| Code Block |
|---|
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.
| 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.
...