Over a million developers have joined DZone.

What Are the Most Common Issues Affecting Integration and APIs?

DZone's Guide to

What Are the Most Common Issues Affecting Integration and APIs?

Failure to adopt good API design practices like ease of adoption, flexible and stable, backward compatibility, migration, and security is a common issue.

· Integration Zone ·
Free Resource

Discover how you can get APIs and microservices to work at true enterprise scale.

To gather insights on the state of integration, API design, and API management, we spoke with 19 executives who are familiar with integration and APIs and asked them, "What are the most common issues you see affecting integration?"

Here's what they told us:

Ease of Adoption

  • Ease of use and UX for the developer or release engineer around APIs. Ability to be run headless. A straightforward path to call the right things in the right order. Make it obvious to the user how to use and what steps to take. Think about legacy support and be concise about deprecating old versions. Some old paradigms are not going to work after a given period and product evolution.
  • Transition around API. SQL skills are common but companies need to shift to APIs. Look at the issue and don’t try to solve with SQL. You need developers used to the languages and frameworks of APIs.

Flexible and Stable

  • Starts with implementation versus being an afterthought. A lot of services lack API flexibility, consistency, and standards. It can be hard to get data out. Poor documentation, Legacy systems without exposed endpoints.
  • If you don’t build for the future, you won’t be able to integrate in six to twelve months. There is a high switching cost. There are issues around security. The more interconnected systems you have the more data is moving and you must ensure the data is secure and not infected. APIs are not that hard to build but people are afraid of them. Take the bull by the horns and design in a way that empowers developers to start making APIs themselves.
  • 1) Not looking at an integration project strategically. Someone in marketing wants to integrate Salesforce with Marketo and contracts with a cloud provider for point-to-point integration. The Integration Center of Excellence need to say, “here are the tools you’re allowed to use.”  You don’t want to end up with 20 different tools to manage. Becomes unmanageable from the cost perspective. These are the approved vendors. Creating a point-to-point integration mess and IT needs to get in front of this. Select a platform that gives you a robust tool set and flexibility. A lot of integration is happening outside of the Center of Excellence today.
  • 1) Must change the organizational model where they have a strategy for publishing their APIs. 2) Decide where to start, which APIs to publish, and where to publish them. 3) Determine what data you have, where it resides, and what you want to expose. Expose more data to monetize. Be prepared for change and for your data to be used in ways you never imagined. You need to be aware of where the opportunities for innovation are.

Backward Compatibility

  • Integrator works with API to get the integration down when someone swaps out the API without telling you. You must debug and fix. Communicate when upgrading APIs. The importance of having an integration mindset. Look at what the customer is trying to accomplish and brainstorm how to address the client problem.
  • Integration architectures often form organically, especially in the enterprise space. This can lead to layers and layers of ad hoc scripting and brittle services... technical debt. Successful architectures embrace organic growth but offer a way to do it safely and in a standardized way. Techniques like Infrastructure as Code, containerization, and a healthy understanding of Conway’s Law will all help you get there.


  • Prioritization of what needs to get done. Some pain drives the first call. Availability of resources at the customer site. Always need a user name or password for access. Getting clients to describe their use case upfront. We need to map the flow of their business. It’s a challenge putting it all together.
  • Legacy-based approach to integration from traditional to API-first. Putting the end user in front of everyone else requires a significant cultural change. Big changes are required in the development workflow. Look at overarching scenarios of consumer use and have empathy for end-users.


  • The most common integration issues stem from not following good API design practices. Often, they are around lack of documentation and security. Poor documentation leads to time delays and buggy implementations. Lapses in security cause far more destruction like data loss, theft, and leaks which directly leads to lost revenue, productivity and reputation for businesses. Lack of clarity in requirements for the integration is another problem where the integration is done for demands other than genuine value for application users. Sometimes, this is done because it is the cool thing to do or to please stakeholders — or in desperate need to demonstrate differentiation. Another scenario where integration projects land in trouble is when, despite establishing the value and viability, one of the communicating entities does not accord it the right priority. A real-world example could be a mobile app needing the services of a back-end web application that does not implement and release API as urgently as required by the app developers.
  • Most SaaS integration partners are used to doing relatively lightweight integrations between products. We push for deeper integrations with not only data but also user experience elements. This requires design thinking for both the integration partner’s product as well as thinking about how to fit content and experience into Atlassian products. The rewards are great, but it requires a bit more time to get this right.


  • Customers have heterogeneous environments and are rapidly onboarding SaaS solutions deciding where to deploy – on-prem, hybrid, or cloud. Need to determine how to handle exceptions. As you deploy more apps, it becomes more of a challenge to manage API design.
  • 1) Authentication errors: Since it's a protection, errors are often obscure to prevent request forging/brute force. 2) In a more general way: Obscure error messages. If you don't tell us what's the problem, it's difficult to resolve it. 3) Outdated documentation, unannounced changes, non-existent documentation. It's so frustrating and time-consuming to try to tackle a bug you don't know the origin of. 4) Difficulties to setup a development environment: they don't code in production, we don't. We should be able to specify whether an API access is aimed for production use or not and simplify the application process.
  • Integration is often more difficult and time-consuming than it should be for developers. The main purpose of integrating with another service is to avoid reinventing the wheel; if there is already a great service for payments that users love, for example, developers are much better off integrating with that service versus developing their own payments solution. However, the backend coding that is required to integrate with existing services is a complex and time-consuming endeavor. It slows down speed to market but it also saps developer energy that is better spent in the front end, building the features that will really differentiate their app.
  • 1) Late to integration, catching up on APIs. 2) New companies with integration adding so many features that they must change APIs and when they do, all the previous integrations break. Releasing every two months. It’s impossible for integration to catch up since it takes three weeks to three months to fix one integration. Products like this will not be adopted by major vendors because the API always requires development. Must come up with something that is compatible is add features and add additional APIs and parameters.
  • Siloed data. Inaccurate reporting. Availability of resources. Knowledge of available solutions in the market to help with integration.
  • Mobile apps are comparatively new, thus there is need of a completely different set of skills than the web. While building mobile apps, it is best to stick with native app development and not compromise on the design elements that are distinctive to each platform.

What other creative use cases have you observed with integration, API design, or API management?

Here’s who we talked to:

  • Murali Palanisamy, E.V.P., Chief Product Officer, AppViewX
  • Kevin Fealey, Director of Automation and Integration Services, Aspect Security
  • Max Mancini, VP of Ecosystem, Atlassian
  • Shawn Ryan, V.P. Product Marketing, Digital as a Service, Axway
  • Parthiv Patel, Technical Marketing Manager, Built.io
  • Chaitanya Gupta, CTO, Flock
  • Anwesa Chatterjee, Director of Product Marketing,  Informatica Cloud
  • Simon Peel, CMO, Jitterbit
  • Keoki Andrus, VP of Products and Steve Bunch, Product Manager APIs and Integrations, Jive
  • Rajesh Ganesan, Director of Product Management, ManageEngine
  • Brooks Crichlow, Vice President, Product Marketing, MongoDB
  • Derek Smith, CEO, Naveego
  • Guillaume Lo Re, Senior Software Engineer, Netvibes
  • Vikas Anand, V.P. Product Management and Strategy – Integration, Oracle
  • Keshav Vasudevan, Product Marketing Manager, SmartBear
  • Kevin Bohan, Director of Product Marketing, TIBCO
  • Pete Chestna, Director of Developer Engagement, Veracode
  • Milt Reder, V.P. of Engineering, Yet Analytics

APIs and microservices are maturing, quickly. Learn what it takes to manage modern APIs and microservices at enterprise scale.

integration ,api design ,api management

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}