When designing APIs, prioritize extensibility and backwards compatibility over convenience. Avoid modifying existing response types or interfaces in ways that could break existing clients. Instead, create new dedicated types, methods, or optional parameters.
When designing APIs, prioritize extensibility and backwards compatibility over convenience. Avoid modifying existing response types or interfaces in ways that could break existing clients. Instead, create new dedicated types, methods, or optional parameters.
Key principles:
Examples:
// Instead of modifying existing ApplicationList
type ApplicationList struct {
Items []Application `json:"items"`
Stats ApplicationListStats `json:"stats,omitempty"` // Breaking change!
}
// Create a dedicated response object
type ApplicationListResponse struct {
Applications ApplicationList `json:"applications"`
Stats ApplicationListStats `json:"stats,omitempty"`
}
// Instead of extending existing interface inappropriately
type Provider interface {
Verify(tokenString string) (*gooidc.IDToken, error)
VerifyJWT(tokenString string) (*jwtgo.Token, error) // Mixing concerns
}
// Create separate interfaces or new implementations
type JWTProvider interface {
VerifyJWT(tokenString string) (*jwtgo.Token, error)
}
// Support optional parameters for extensibility
func NewClient(repoURL string, creds Creds, opts ...ClientOpts) (Client, error) {
// Allows adding new options without breaking existing calls
}
This approach ensures APIs can evolve gracefully while maintaining compatibility with existing integrations.
Enter the URL of a public GitHub repository