Blog

Integration and API news for developers

The API Interviews – The Challenges of Working with APIs

20th November 2018

Ian Rimmer - Connector Wizard 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 getting 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 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 API’s are ones that are consistent structure of endpoints and data structure across the board. Clear and concise documentation make 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, response is JSON or just a string dependant 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 so that it is more user friendly. This 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, later built out with more customer focused uses. This process can leave the API in a bit of a messy structure, but 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 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?

FrustrationEvolved design for internal purposes and not stepping back to think on a higher level as 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, so 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?

The same as the service I am integrating from 😀

In seriousness, you just should use standards and consistency and 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 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 process, 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 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.

Found this content useful? Then why not share it!