The graphic has the title of the press release and Halfaker's logo

5 Common API Design Flaws and How to Fix Them

The IT development landscape is continually evolving to meet customer needs and requirements. As businesses continue to integrate internally and adopt new mobile applications, devices, and cloud applications, the demand for API development is growing. In this modern cloud-based environment, APIs are crucial to ensuring fast, seamless, and secure data exchanges between systems.

What Are APIs?

Application Program Interfaces, or APIs, are sets of definitions for building out and integrating software applications. In layman’s terms, APIs are the behind-the-scenes instructions that tell products and services what kinds of information they can exchange with one another, and how those exchanges take place. Leveraging a common set of instructions saves time and money, increases collaboration across business and IT teams, and simplifies design and development. APIs also provide a layer of security since the product(s)/service(s) that communicate to each other do so in small data packages, never sharing all of their information.

Thoughtful API design is crucial: If an API is not developed correctly, the key link between product/service is inefficient and the products and services are unable to effectively communicate and share data. Below, we’ll review five of the most common API design flaws and how to fix them.

Design Flaw #1: Not Thinking About Performance from the Get-Go

Today’s business users and consumers require lightning-fast response time from their tools and applications. The average time it takes to resolve a user request is only a little over one second. That may not sound like a long time, but even one second has become ‘slow’ to users who have become increasingly accustomed to instant results. Thus, taking performance into account when designing APIs is incredibly important from both a developer and business perspective. Some important considerations to ensure fast performance include ensuring documentation is complete and clear, checking resource names to confirm they follow naming conventions, and ensuring the data is well structured and easy to understand and use.

Not Testing your APIs

All the best API development practices in the world will not deliver great results if you don’t properly test your APIs; however, APIs are often overlooked during testing. In Halfaker’s experience, the most effective way to test APIs is via Automated Testing. While end-to-end and unit testing have their own benefits, we’ve found that Automated Testing attains the best of both worlds. It allows for an increased scope when compared to unit tests and helps avoid testing issues in distributed applications in which the scope of one application ends and the next one starts. In addition, Automated Testing increases the stability and speed of execution.

As an example, Halfaker executes Automated Testing for the Department of Veterans Affairs (VA) in to enforce quality early and throughout the process. To ensure fewer downstream issues, we hold frequent ongoing meetings with stakeholders and business, create a roadmap of future builds, establish common terminology, and utilize Automated Testing to enforce build quality throughout API development. Consider leveraging tools such as, Mulesoft, Tibisco Business Works, Oracle Fusion Middleware, AWS API Gateway, Kong, Azure, Postman to automate key processes including API creation, testing, publication, security, monitoring and reporting. This automation supports API Management throughout the entire development process. Read on to learn more about how API Management can be a critical component of success in API development.

Design Flaw #3: Lack of API Management

API management is the process of creating and publishing APIs, enforcing their usage policies, controlling access, collecting and analyzing usage statistics, and reporting on performance. In simple terms, API management ensures that APIs are consumable and secure. Much like testing, API management can be a make-or-break element of your organization’s API success.

Even with an API management process in place, it is still easy to overlook security. If your organization doesn’t do this already, you should include your security team in the API development process. Doing so ensures your team is looking at the process holistically to reduce security risks.

Automation can increase the efficacy of your API management practices. For example, by using automation to apply monthly updates and ensure system recovery and compliance, Halfaker was able to provide VA stakeholders with what they wanted from the beginning and were able to reduce time and overall cost.

By managing an API throughout its lifecycle and including business, developer, and security teams in developing oversight, businesses can reduce overhead, automate API infrastructure, and improve usability and security.

Design Flaw #4: The API Was Not Designed Correctly

If your API is not easy to read, work with, and/or is not complete or concise, developers will not understand it or have to constantly refer back to the code to remember how to use it, resulting in a higher level of effort and decreased usability. Poorly designed APIs can hamper future development, result in longer resolution times, and generate an unending stream of support calls as end users struggle to use the system.

A good API should be easy to read so developers can quickly memorize the code and not have to refer back to any notes. An API should also be hard to misuse and should not enforce strict guidelines on the user. Lastly, keeping an API complete and concise will not only enable developers to make full-fledged applications after the first iteration is over, but also enable them to build on top of the existing APIs.

Design Flaw #5: Poorly Written Error Codes

An error response sounds like the last thing you want to see when using an API, but they can be incredibly helpful. Error codes enable developers to communicate failure to the user by showing the user specifically what went wrong, why the intended functionality did not work, and the best way to resolve the issue. The worse thing the end user can see after submitting a request is a vague error code such as “404 Terrible Request.” These types of error codes offer no insight into why the failure occurred or how to resolve it, and only create frustrations and an overall poor customer experience.

To create a good error code, use the HTTP status code format to communicate to the user what is happening on the back end after they submit a poor request and receive an error message. Be sure to prefix the code with the appropriate numeral to convey protocol states and the state of the initial request.

Along with an informative error message, the inclusion of an internal reference ID and an error summary is incredibly useful to end users as well. Error summaries on top of HTTP status codes and/or an interface reference ID allow the user to view the context, cause, and solution for the error. Well-written error codes can speed up resolution time since the user may be able to resolve it themselves, resulting in an overall better customer experience and increased business value.


As is evident, there are many benefits to well-designed APIs, and we hope that our own deep experience can help you resolve and avoid some of the common pitfalls we shared.

Halfaker currently supports several large API-driven programs for VA and the Department of Defense. We develop FHIR/REST APIs, RESTful Swagger APIs, and mobile APIs to promote optimal system interoperability and lower total cost of ownership. Halfaker assesses a number of criteria when developing and managing APIs, including value proposition, interface control specification, authentication and authorization; automatic code generation, protocols and formats, licensing, languages, and monitoring and logging capabilities to meet unique customer needs.

With carefully designed APIs, you can reduce costs and development time, improve customer experience, and increase collaboration between IT and business.