Inconsistent Error Handling and Response Types in JiraServiceDeskApiService

[luckberonne]

Description
The JiraServiceDeskApiService interface has inconsistent return types and lacks proper error handling mechanisms, which could lead to unpredictable behavior and maintenance challenges.

Current Behavior

• Methods like addIssue() and addIssueAttachment() return raw ResponseEntity objects without type parameters
• getIssuesSummary() returns a DTO object directly while other methods return ResponseEntity
• syncUserJiraAccountId() returns a String without clear documentation on what this represents
• No standardized approach for error handling is defined in the interface

Expected Behavior

• Consistent return types across all service methods
• Properly parameterized ResponseEntity objects (e.g., ResponseEntity)
• Clear error handling strategy defined at interface level
• Comprehensive documentation for each method's purpose and return values

Technical Details

// Current problematic methods
public ResponseEntity addIssue(String jsonData, CustomUserDetails curUser);
public ResponseEntity addIssueAttachment(MultipartFile file, String issueId);

Impact

• Inconsistent response handling across client code
• Difficulty in implementing proper error handling in consuming code
• Potential for runtime errors when processing responses
• Reduced maintainability and increased technical debt

Suggested Solution
Refactor the interface to use consistent, parameterized return types and add comprehensive documentation:

/**
 * Service for interacting with the Jira Service Desk API.
 */
public interface JiraServiceDeskApiService {
    /**
     * Creates a new issue in Jira Service Desk.
     * @param jsonData JSON representation of the issue
     * @param curUser Current authenticated user
     * @return Response containing the created issue details or error information
     */
    ResponseEntity<IssueResponse> addIssue(String jsonData, CustomUserDetails curUser);
    
    // Similar improvements for other methods
} 

[Akilan247]

Hi @luckberonne, thanks for raising this issue — I completely agree with your points about the inconsistencies.

I’d love to contribute by refactoring the JiraServiceDeskApiService interface to use consistent return types, improve error handling, and add proper documentation as suggested.

Let me know if you’re okay with me picking this up or if there are any guidelines you'd like me to follow.