Standardize response formats and pagination defaults across modules #6

New Issue

b3nw · 2025-07-11T15:09:11-05:00

b3nw commented

2025-07-11 15:09:11 -05:00

Enhancement: Improve API Consistency

Issue Description

Several inconsistencies exist across modules that should be standardized to improve the overall API experience and developer expectations.

Inconsistencies Identified

1. Delete Operation Response Formats

Current State: Different modules use different response formats for delete operations

Milestone/Label Modules:

{
  "success": true, 
  "message": "Milestone 1 deleted successfully"
}

Repo Module:

"Fork success"

Recommendation: Standardize on one approach across all modules.

2. Pagination Parameter Naming

Current State: Different modules use different parameter names and defaults

Module	Parameter Name	Default Value
Issue	pageSize	100
Milestone	limit	10
Label	limit	50
User	pageSize	100

Recommendation: Standardize on either pageSize or limit with consistent default values.

3. Error Message Formats

Current State: Slight variations in error message formatting

Examples:

"failed to get milestone: %v"
"invalid label ID at index %d"
"Label %d deleted successfully"

Recommendation: Establish consistent error message patterns and casing.

Proposed Solutions

1. Standardize Delete Responses

Option A: Use structured responses everywhere

return to.TextResult(map[string]interface{}{
    "success": true,
    "message": fmt.Sprintf("%s deleted successfully", resourceType),
})

Option B: Use simple text responses everywhere

return to.TextResult(fmt.Sprintf("%s deleted successfully", resourceType))

2. Standardize Pagination

Recommendation: Use limit with default value of 50 across all modules

Reasonable default for most use cases
Consistent naming
Allows users to adjust based on needs

3. Error Message Guidelines

Patterns:

Start with lowercase (unless proper noun)
Use consistent verb tenses
Include context where helpful
Follow format: "action failed: reason"

Implementation Plan

Review all modules for response format consistency
Create constants for default pagination values
Update function signatures to use consistent parameter names
Establish error message style guide
Update tests to match new formats

Affected Files

/operation/milestone/milestone.go
/operation/label/label.go
/operation/issue/issue.go
/operation/repo/repo.go
/operation/user/user.go

Priority

Low - API improvement that enhances developer experience

Breaking Change Consideration

Some of these changes may be breaking changes for existing users. Consider:

Implementing gradually
Documenting changes clearly
Potentially supporting both formats temporarily

# Enhancement: Improve API Consistency ## Issue Description Several inconsistencies exist across modules that should be standardized to improve the overall API experience and developer expectations. ## Inconsistencies Identified ### 1. Delete Operation Response Formats **Current State**: Different modules use different response formats for delete operations **Milestone/Label Modules**: ```json { "success": true, "message": "Milestone 1 deleted successfully" } ``` **Repo Module**: ```text "Fork success" ``` **Recommendation**: Standardize on one approach across all modules. ### 2. Pagination Parameter Naming **Current State**: Different modules use different parameter names and defaults | Module | Parameter Name | Default Value | |--------|----------------|---------------| | Issue | pageSize | 100 | | Milestone | limit | 10 | | Label | limit | 50 | | User | pageSize | 100 | **Recommendation**: Standardize on either `pageSize` or `limit` with consistent default values. ### 3. Error Message Formats **Current State**: Slight variations in error message formatting **Examples**: - `"failed to get milestone: %v"` - `"invalid label ID at index %d"` - `"Label %d deleted successfully"` **Recommendation**: Establish consistent error message patterns and casing. ## Proposed Solutions ### 1. Standardize Delete Responses **Option A**: Use structured responses everywhere ```go return to.TextResult(map[string]interface{}{ "success": true, "message": fmt.Sprintf("%s deleted successfully", resourceType), }) ``` **Option B**: Use simple text responses everywhere ```go return to.TextResult(fmt.Sprintf("%s deleted successfully", resourceType)) ``` ### 2. Standardize Pagination **Recommendation**: Use `limit` with default value of `50` across all modules - Reasonable default for most use cases - Consistent naming - Allows users to adjust based on needs ### 3. Error Message Guidelines **Patterns**: - Start with lowercase (unless proper noun) - Use consistent verb tenses - Include context where helpful - Follow format: `"action failed: reason"` ## Implementation Plan 1. Review all modules for response format consistency 2. Create constants for default pagination values 3. Update function signatures to use consistent parameter names 4. Establish error message style guide 5. Update tests to match new formats ## Affected Files - `/operation/milestone/milestone.go` - `/operation/label/label.go` - `/operation/issue/issue.go` - `/operation/repo/repo.go` - `/operation/user/user.go` ## Priority **Low** - API improvement that enhances developer experience ## Breaking Change Consideration Some of these changes may be breaking changes for existing users. Consider: - Implementing gradually - Documenting changes clearly - Potentially supporting both formats temporarily

b3nw added the enhancement label 2025-07-11 15:09:16 -05:00

b3nw closed this issue

2025-07-11 15:27:46 -05:00

This repo is archived. You cannot comment on issues.

1 Participants

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: b3nw/gitea-mcp#6