Introduction

The Hidden Costs of Inconsistent API Naming Conventions - by Ikenna Nwaiwu

The Governance Dilemma

At an API governance meeting recently, someone asked, "But should we bother having an API style guide rule on casing convention for message bodies?" The context was an organisation in the early stages of implementing API governance and strengthening its API style guide, which lacked recommendations on casing conventions for message bodies.

The organisation's API landscape was diverse: some APIs used kebab-case, others used camelCase, snake_case, and various other conventions. We were considering adding a rule to the API style guide and an associated linting rule that would recommend camelCase for all new APIs. During this conversation, the question about standardisation’s actual value arose.

The "Do Nothing" Approach Isn't Free

As a consultant, I present the pros and cons of any approach, make recommendations, and ultimately let the client make the final decision. While not establishing a convention might appear to have a low initial implementation cost (the "do nothing" option), the long-term costs can be surprisingly high.

Limited API Reuse Potential

The most significant hidden cost is the severe limitation on API reuse. When data models and API components look structurally similar but use different casing conventions, they cannot be easily extracted to reduce duplication. Consider this real-world example:

Despite these APIs representing the same fundamental entity, the inconsistent naming makes it nearly impossible to create a shared customer data model or reusable components without significant refactoring.

Organisations often resist standardisation due to concerns about legacy system compatibility, team autonomy, or the perceived cost of change. However, these short-term concerns frequently overshadow the long-term technical debt accumulation

Degraded Developer Experience

The second major cost is the negative impact on developer experience. Developers consuming multiple APIs from the same organisation can become frustrated when identical concepts are named differently across services. This inconsistency:

• Increases cognitive load

• Requires more thorough documentation

• Complicates data mapping between services

• Makes API behavior less predictable

• Slows down development velocity

Recommendations

Based on my experience across multiple organisations, I recommend:

1. Choose a single casing convention that aligns with your primary development ecosystem.
   When starting out on implementing API governance, you can do a rough check of which conventions are more frequently used in your existing OpenAPI descriptions by using Large Language Models (LLMs). If it is appropriate to do so within your organisation's security policy (considering data sensitivity and third-party processing concerns), uploading your OpenAPI files with a prompt like the following can help identify existing patterns: "Take the role of a software engineer skilled in API design. Identify all the casing conventions used in the attached OpenAPI definition files." Be mindful of the context window limitations of your chosen LLM when uploading multiple or large files. Once you've identified the dominant conventions in your existing APIs, you can make an informed decision about standardisation going forward.

2. Document this standard clearly in your API style guide

3. Implement automated linting to catch deviations early.

4. Consider a grace period for existing APIs, with standardisation applied during their next major version update.

5. Create a shared library of reusable data models that follow the convention.

While perfect consistency may not be achievable immediately, having a clear direction dramatically improves both API reusability and developer experience over time.

What's Your Experience?

Have you struggled with inconsistent naming conventions across APIs in your organisation? What approach has worked best for you in standardising these practices? I would love to hear about your experiences and solutions.

Tyk's Upcoming API Governance Solution

Tyk’s Leap 2.0 API Governance Conference took place on February 27, 2025, where Tyk provided a sneak preview of its upcoming API governance solution. The Tyk Universal API Governance Platform (which I'll abbreviate to TUAGP) is designed to help enterprises create a strategy to enforce API governance across teams and environments. For those unfamiliar, Tyk is a leading provider of API connectivity platforms, recognised for its open-source, cloud-native API gateway. In my post on LinkedIn, I share my initial impressions of TUAGP based on the features presented at the conference. Check it out.

API Governance Consulting

Is poor API governance slowing down your delivery? I'll provide expert guidance and a tailored roadmap to transform your API practices. Schedule your consultation here