"For consumers, a bad API means a longer development cycle and a higher defect rate; and in some cases, even a skills problem in the team" - Peter Hendriks, IT architect at Infosupport
Generally, developers will pay close attention to server side scripting and may at times neglect the client side. When you load a website, your browser will stop the build of the page, check for any API's, get the widget and then load the page. What this means is that if the client side scripting is poor, it will increase the page load time. Users may in turn get frustrated with your website's lengthy load times, compromising the effectiveness of the API.
Another commonly made mistake is failing to watch for hang time. When the API software pulls in information, works off that, and pushes out data, the time it takes to build the required output is called hang time. While it's waiting to get the output it will not give you any response. As a result, the data is not relayed in an efficient manner. Picture a movie you're downloading. In order to watch the movie, you would have to wait until the download is finished. One solution in PHP is the Object Flush, where you flush out your data, even before you think you have the full response. As a result, you can essentially watch the movie before it's finished downloading.
The next pitfall concerns legal complications. Ideally, the third party API you're using should allow you to legally use the data the way you want to use it. If there are restrictions in place and you have to alter the API functionality or use it in an inefficient manner, deploying the API may not be in your best interests. That is where you conduct a cost-benefit analysis to work out the actual value of the third party API and whether it would be worth building your own.
At times, software engineers can get caught up in the problem and overthink it. Usually, the best APIs and the easiest to implement are the simplest. Trying to create a common response for all APIs is unwise. It creates unnecessary complications. Getting user information is different from getting a video information, which is different from posting a comment, which is different from getting a list of followers.
Another important consideration is ensuring the URL's are consistent. This can be compared to naming convention. Make sure the API's URL stems and query string have a strong logic to it. For example, to get profiles use api.workingmouse.com/profiles.php, but to get images use api.workingmouse.com/images/get.php. Thinking as "objects" and "actions" is a good start. It's another way of simplifying your API and enhancing the user experience.