The API Interviews – The Challenges of Working with APIs

Updated on by Daniel Twigg

Key API Integration Features

Welcome to the API Interviews! We’re kicking off our new series looking at working with APIs and API challenges by speaking to developers on the front line.

In our first article of the series, we have been talking with Cyclr’s Connector Team Development Leader, Ian Rimmer about API challenges.

Ian Rimmer - Connector Team Lead

Challenges working with third-party APIs

What’s the biggest challenge you face working with third-party APIs?

There are several large API challenges developers face regularly. Personally, I’d say the biggest challenge or frustration for me is API documentation. The lack of information provided in some docs can take developers by surprise. This is because sometimes they don’t show the real request/response information. As a result, developers will have to manually call the API to prove the data.

As well as that, API developers struggle to find the correct credentials for testing or access to a live system within the documentation. Without this important information, developers are unable to do API testing and prove the API integration functions correctly.

Another issue I’ve found with API documentation is that it usually omits some details. For example, the documentation says returns true or false, but what it doesn’t say is that returns true as true not {true} or {“status”: true}.

So, without access to documentation and a live service (ideally a sandbox account), it can be an uphill struggle of detective work to understand the API in question.

API Usability

If you were to rank APIs by usability, easy to work with at one end and difficult at the other, what characteristics would you find at either end of the spectrum?

Let’s start with the easy APIs. They typically have a consistent structure of endpoints and data across the board. They have clear and concise documentation that makes a world of difference for developers. Especially, if the documentation includes an interactive format that lets you make real calls even better. As well as, if they have used the OpenAPI standard. The standardised formatting makes it easy for multiple developers to interpret the API.

Difficult APIs on the other hand, are inconsistent, for instance, the information they provide is lacking from post to submit data, the response is JSON or just a string dependent on the endpoint called. As well this they use an unconventional data structure and field names. Finally, their documentation is very limited, not showing real headers, data requests, and responses or structures of entities.

Modifying API Functionality

Can you tell us about an instance where you’ve had to create custom functionality that the API doesn’t naturally support?

A common API challenge is that they don’t naturally support certain functionality. This means a developer will need to create custom functionality and it’ll need to obfuscate the complexity of the UI if there is any bespoke authentication. For example, if oAuth2 is used then it needs to call a login endpoint and include header information in subsequent API calls.

While creating connectors in Cyclr, our developers often have to manipulate and normalise data. This makes it more user-friendly. As well as allows the third-party applications to “play well” with other apps in an integration workflow.

This can become quite a task where no standard submission of data is defined which is common with APIs that were built with an internal use initially and later built out with more customer-focused uses. The process can leave the API in a bit of a messy structure. However, our developers are able to correct much of this during the API connector curation process.

Another common custom function is the ability to filter out records based on a time range. This allows us to fetch only the latest records. Rather than collecting the whole data set. We use this “Get New…” function on many of our connectors, which in most cases is a custom function in Cyclr rather than something built into the API.

API Development Challenges

What are the most common mistakes made by people working with APIs?

One common mistake occurs when an API is developed by a person who does not know how their application\service works from an external user’s point of view. As a result, the design of the API suffers and is only evolved for internal purposes. They would benefit from taking a step back and trying to think on a higher level as to how would an outsider view this service.

This is because you cannot guess how someone is going to call your service/API. Therefore make sure you can communicate best practices for interacting with it.

Without this, it leads to not including defensive coding or rate limits and paging; tools you should use to dictate how your API is interacted with, as well as measures to prevent abuse.

The Perfect API

What would your ideal API look like?

For me, an ideal API should use standards and consistency and it should be able to communicate this information to those who are strangers to your product and API. They should also use patterns and standards that exist across the web; OPEN API documentation, and OAuth2.

If you need to do something bespoke ensure that there is a reason for it, or a reason why is no one else doing it like this and document this well in the API documentation.

My ideal API would also have the ability to filter or mine records you are interested in. For example, in our system, we deal with workflows and repeated processes. Therefore, all records should have created and modified dates and the API calls have filters for this information. The API would restrict the fields being returned to the ones I am interested in. No need for every column in the record where I only want to check if it exists or has changed.

API Tools

Are there any particular tools that you swear by when working with APIs?

To me, the right tools are really important as well as access to the API and using Postman or SOAP UI to make a real call to verify and play with the API. As well as confirming the documentation and interacting with the API to understand it.

Thank you Ian for sharing your thoughts on API challenges!

So, there you have it API challenges are real and as Ian has mentioned there are numerous ways to curtail these challenges by following a conventional structure, building useful and readable API documentation as well as how you can build an ideal API from someone who works with them every day!

Wondering what an API connector is? Watch below!

If you are using our Cyclr platform or are just interested in how it works feel free to check out our documentation

Looking for more about working with APIs? Read our two other interviews

About Author

Avatar for Daniel Twigg

Daniel Twigg

With over 12 years experience in the Digital Marketing arena, covering industries including IoT, SaaS, fitness, computer gaming and music, Daniel has been Cyclr's marketing manager from the early days of the platform. Follow Daniel on LinkedIn

Ready to start your integration journey?

Recommended by G2 users

Book a demo to see Cyclr in action and start creating integration solutions for your customers