Discovering APIs: 10 must-haves before you set foot on land.
I’ve wasted hours of my life on builds that consume an API that gets me 90% of the way there due to half-reading documentation. If you are a developer, read! Have at least a rough sketch of the calls you will be using and what logic you need to fill in the gaps. If you are approaching an implementation from the business side, don’t buy into a provider without consulting the technical teams who will be consuming it.
So here I am. About to build a new project that is going to touch maybe five different services. I know one of them needs to be location but I don’t even know what location services are out there. Spending the time to find and evaluate proper dependencies is a huge blocker during design.
Thankfully, Postman has a solution for this: The API Network. It’s a portal that allows you to search through thousands of APIs that have been submitted as collections. You can even submit one yourself!
To quote Postman Founder Abhinav Asthana, “APIs are both technical and business abstractions.” Unless you are just backyard hacking, consider both parts holistically. In order to do that, The first thing you should do before cracking into any API is ensure the necessary functionality is there. If both business and technical requirements are not met from the outset, then you’ve “discovered” the wrong continent, Columbus.
After playing with the API for a bit, I’m feeling good that it has what I need to finish this POC. Now it’s time for due diligence. I use my go-to list of characteristics of a good API to consume as a developer:
- Documentation — When was the last time the documentation was updated? Out of date docs are the first thing that sends me running. Does the documentation have companion tutorials in relevant technologies? Is the text itself readable and empathetic with how you as a developer will be using this API? If the official guides are lacking, are there strong ones in the community? Bonus points if the walkthroughs are interactive, see Okta’s Postman collections page!
- Community and Support — Is there an online community? Is it active? How much StackOverflow traffic is there? If the API is open source, are there frequent contributions? Is there a demonstrated quality gate for merges/pull requests? Do the API providers listen to the community by doing things like actually implementing feature requests or logging bugs publicly? Are client libraries being actively maintained?
- Maintenance and Forward Communication —Are versioning guidelines clear? Have previous versions been sensibly deprecated, or left to rot? It is unacceptable for your product to break due to a poorly chosen rogue dependency. Is a public roadmap provided? We maintain a public roadmap for developers, in addition to a public issue tracker — even for internal bugs. The previous two points should make this pretty clear. If no one from the team has posted or responded online and there seem to be no upcoming releases, despite months since last activity, it’s time to look somewhere else.
- Design, Technology, and Implementation — Does the API follow REST specifications? Is it using HTTP methods correctly, or is everything either a GET or a POST? Is the structure of endpoints logical and scalable with load? You should believe in the technology behind your dependency, and know how that technology works. Won’t be caught dead integrating with a SOAP API? Convinced GraphQL is going to take over the API space despite its relative youth? Perhaps you only have experience developing with REST API’s and need to stick to what is comfortable? If your team uses OpenAPI as an a source of truth but the API provides definitions exclusively in RAML, there may be on-boarding friction.
- Performance, Resilience, and Agility — Is the API fast enough to be used without impact the responsiveness of your service? Is it still that fast during peak traffic, or when handling worst-case requests with heavy payloads? Have there been major or frequent service interruptions in the past? Did the team not only respond well to them, but patch, adapt, and improve after? Are they quick to identify and update with necessary functionality or improvements?
Characteristics I look for before choosing an API to consume as a business:
- Pricing —Does it cost anything? Is this API SaaS? Is their model reasonable, or can I expect a $400 charge because a junior programmer forgot to terminate a loop?
- Terms of Service and Legality — Don’t just assume here. Ensure that it’s legal to consume the API for your use case, otherwise you are opening yourself up to a boatload of legal trouble.
- Privacy, Security, and Authentication — Are there any protections on the API? Do its security specifications meet the standards of your own? Has the provider had any incidents with hacks or breaches in the past? What technologies are used and do you know how to work with them? What are you telling the API provider with your usage? Can you ensure that you aren’t leaking sensitive client/customer information like PII?
- Ecosystem — are other companies building on this platform? Can you expect to be working among peers? If you are in a specific domain, will incoming developers have transferrable knowledge of this API?
- Maturity — Here at Postman we have a maturity model we use to evaluate our internal APIs. Although consuming an external dependency does have slightly different concerns, the idea of summing up the previous 9 points into a single metric will make your ultimate decision a simple one.
After walking through all of the above, I’m satisfied that this API is perfect for my project. I can complete the POC, and finally finish up design. As a final challenge to you, go check out the API Network and find something you might want to consume. Evaluate it!
