The API Interviews – The Challenges of Working with APIs

Updated on by Daniel Twigg

Ian Rimmer - Connector Team Lead dealing with APIs

Welcome to the API Interviews! We’re kicking off our new series looking at working with APIs 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.

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

There are several large hurdles we face regularly, but API documentation can be a surprising challenge at times. If the documentation does not show the real request/response information then we need to manually call the API to prove the data.

To compound this, it can be a challenge to get credentials or access to a test or live system. Without this, we are unable to test and prove the API integration functions correctly.

Documentation usually omits some details. For example, returns true or false. What the documentation did not say is returns true as true not {true} or {“status”:true}. So to sum up without access to documentation and a live service (ideally a sandbox account) it is an uphill struggle of detective work to understand the API.

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?

Easy APIs are ones that are a consistent structure of endpoints and data structure across the board. Clear and concise documentation makes the world of difference. If that includes an interactive format that lets you make real calls even better! OpenAPI standard is a plus too, the standardised formatting makes it easy for multiple developers to interpret the API.

Difficult APIs are inconsistent. i.e. Form post to submit data, the response is JSON or just a string dependent on the endpoint called. Data structure and field names not following a convention. Documentation is very limited, not showing real headers, data requests, and responses or structures of entities.

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

Usually, custom functionality will be needed 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, we often have to manipulate and normalise data. This makes it more user-friendly. As well as allows the third-party application to “play well” with other applications in an integration workflow.
This can become quite a task where no standard submission of data is defined. This 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. Luckily we 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.

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

Evolved design for internal purposes and not stepping back to think on a higher level as to how would an outsider view this service. This can often be developed by a person who does not know how their application\service works from an external user’s point of view.

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.

What would your ideal API look like?

My ideal API should use standards and consistency. It should be able to communicate this information to those who are strangers to your product and API. Use patterns and standards that exist across the web; OPEN API documentation, OAuth2.

Where you do something bespoke ensure that there is a reason for it, or a reason why is no one else doing it like this.

The ideal API would have the ability to filter or mine the records you are interested in. In our system we deal with workflows and repeated processes, so all records should have created and modified dates and the API calls have filters for this information.

Also, it 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.

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

Access to the API and using Postman or SOAP UI to make a real call to verify and play with the API, confirming the documentation and interacting with the API to understand it.

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

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.

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