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

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.

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.

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.

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.

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.