The API Interviews – The Challenges of Working with 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.

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.

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.

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.

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.

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.