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 name Issue.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';

    JS

  • Denotes grouping for Fluent API groups. The sameDo 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 the Do transition  (original name) full function name is performIssueTransition:
  

  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: