Jira Server Managed API
Before reading this documentation make sure you have read the baseline documentation.
Jira Server Managed API implementation details can be found here.
Implementation details table contains the following columns:
- Original Grouping - This is the original group name that Atlassian has given in a form of REST API endpoint's URL path.
- Original Function Name - This is the original function name that Atlassian has given.
- Status - Managed API status, any function that has green status can be expected to have full Managed API support.
- Remapped Grouping - Grouping used in Managed API level, please note, the Managed API grouping can differ from the official vendor's grouping strategy, mostly for convenience and consistency sake. Remapped groupings are used for following cases:
Denotes an import path for the function when working on HTTP API or Managed API level. For example
Do transition
(original name) with remapped group nameIssue.Transition
and with remapped function full nameperformIssueTransition
can be imported from following locations:// HTTP API import { performIssueTransition } from '@avst-hzn/jira7-server-api/http-api/issue/transition'; // Managed API import { performIssueTransition } from '@avst-hzn/jira7-server-api/managed-api/issue/transition';
JSDenotes grouping for Fluent API groups. The same
Do transition
(original name) with remapped group nameIssue.Transition
and with remapped function short nameperformTransition
can be used as following:import { JiraServerConnection } from '@avst-hzn/jira7-server-api'; export async function run() { const JiraServer = JiraServerConnection.connect('CONNECTION_ID'); await JiraServer.Issue.Transition.performTransition({ ... }); }
JS
Remapped Function Short Name - Short function name is used in Fluent API level as shown above, exception being when function is accessed via
All
group then the function full name will be used as following, where theDo transition
(original name) full function name isperformIssueTransition
:import { JiraServerConnection } from '@avst-hzn/jira7-server-api'; export async function run() { const JiraServer = JiraServerConnection.connect('CONNECTION_ID'); await JiraServer.All.performIssueTransition({ ... }); }
JS- Remapped Function Full Name - Full function name used in HTTP API, Managed API and Fluent API level, but only on Fluent API level when the function is accessed via
All
group as shown above, otherwise a short name is used.
Error handling
Error handling adheres to the same rules as outlined in the base documentation, with a minor addition where HttpError
has a generic type that is always AtlassianErrorResponse
which denotes the body type of the HTTP error response. It can be used in following ways:
import { JiraServerConnection } from '@avst-hzn/jira7-server-api';
import { HttpError } from '@avst-hzn/api-common';
import { AtlassianErrorResponse } from '@avst-hzn/jira7-server-api/common';
export async function run() {
const JiraServer = JiraServerConnection.connect('CONNECTION_ID');
// Promise style
JiraServer.Issue.getIssue({
issueIdOrKey: 'ISSUE-1'
})
.then(issue => {
// Do something with the issue
})
.catch(error => {
if (error instanceof HttpError) {
console.error(error.response.body.errorMessages.join(', ')) // Print out Jira error messages that were sent back
}
});
// Async/await style
try {
const issue = await JiraServer.Issue.getIssue({
issueIdOrKey: 'ISSUE-1'
});
// Do something with the issue
} catch (error) {
if (error instanceof HttpError) {
const body = error.response.body as AtlassianErrorResponse; // Explicit type cast is needed here because HttpError's generic type cannot be automatically inferred the same way as it works in Promise based example
console.error(body.errorMessages.join(', ')) // Print out Jira error messages that were sent back
}
}
// Using error strategy
const issue = await JiraServer.Issue.getIssue({
issueIdOrKey: 'ISSUE-1',
errorStrategy: {
handleHttpAnyError: error => {
console.error(error.response.body.errorMessages.join(', ')) // Print out Jira error messages that were sent back
return null; // Return null if something goes wrong
}
}
});
if (issue) {
// Do something with issue
}
}
Common HTTP Errors
As mentioned in the baseline documentation that in place of common HTTP errors instead of throwing HttpError
a more specific error is thrown that can be caught directly. Since more specific errors derive from HttpError
you can still catch that one too.
Here is a mapping of common HTTP errors and error types that they are represented by:
HTTP Error | Error Type |
---|---|
400 | BadRequestError |
401 | UnauthorizedError |
403 | ForbiddenError |
404 | NotFoundError |
429 | TooManyRequestsError |
5xx | ServerError |