Making the Most of Third-Party APIs
How Do You Spell API?" is a new monthly blog series where Mashery experts break down complex API-related topics into language we can all understand.
It’s the panacea we all dream about when it comes to APIs: the ability to grow your business and your brand awareness beyond your current development team, and likewise, the ability to build robust features into your application by leveraging someone else’s work. A third-party API can be any API that was built outside the control of your team, whether it is another internal team at your company with whom you are interfacing or whether it’s an external provider.
There is an implicit trust factor at work when you embrace someone else’s APIs. You trust that the APIs you consume are well-maintained and stable. But, as with all things in life, trust is based on experience and knowledge. So how do developers decide where to place their trust when it comes to third-party APIs?
Let’s look at some ways to ensure that the APIs you consume live up to their promise and are worthy of your trust.
We say it all the time because it’s true. It starts with the documentation. For the API provider, the documentation is where developers first meet the API – consider it that first glance across a crowded dance floor. How do you know right away that they are the ones you want to dance with? Good API providers:
- Make it clean and well-organized
- Don’t skimp on details developers need in order to be successful.
- Show examples of what a request and response look like
- Tell you what you can expect from them – how often do they update their API and how will they communicate changes, for example
- Make it interactive – developers like to experiment on their own. There are a lot of tools out there that provide a way to interact with the API within the docs.
How much effort your API provider puts into their documentation says a lot about their relationship with you. Even the most well-crafted API may fail you if the provider doesn’t communicate well with their developers.
Documentation is only part of the story. You are about to enter into a relationship with this provider, even if the API they provide is free and open. Before you decide that you want to make their code part of yours, do a little research to see how well they’ve performed over time and how widely adopted they are. A few questions to ask are:
- Can they handle the number of transactions you’re expecting?
- How widely adopted are they?
- What’s their uptime over time?
- How many times have they updated or deprecated their APIs?
- Where are they hosted and how reliable is that platform?
Testing and Monitoring
Many of us use third-party APIs because it gives us the opportunity to leverage work someone else has already done. But the obvious downside to leveraging their work is that you also inherit their mistakes and bad practices. Even after you have read their documentation and done their research, you still have to decide for yourself how much risk you want to incur. If your application depends on their API, you should treat it as if it were own:
- Include it in your sprint test plans
- Write some automated tests to hit the API regularly so you can be sure that it is providing the response you expect
- Don’t forget to add it to your production monitoring it as if it were an essential part of your own code, because it is.
- Have a plan in place for alerting your own customers when your API provider has downtime
- Put some backup plans in place so you can weather an outage on their side without being inaccessible yourself
Mitigating the Risk
In the end, it’s about making sure that the layers of dependency you put in place don’t jeopardize your business goals or API strategy. If you have adopted someone else’s API (whether it’s another internal group or an external provider), you are still responsible for the application your users depend on. Before you place your trust in an API, make sure it is worthy.
Contact us if we can help!