API Docs by Request
While it’s all the rage to make your API docs publicly available, is it such a good idea? Just because Twilio blabs to any random person about exactly how to make a phone call with their API does that mean you should? If Twilio stuck their head into the oven would you do it too?
There are a bunch of good reasons to make people jump through hoops to get access to your API docs. I’m hoping that a quick reminder of a few of them will confirm your belief that it’s totally OK to require a developer to talk to a salesperson before emailing them a PDF.
Reason #1: Bespoke Onboarding
Every customer is unique, right? And as everyone knows, the customer is always right. When it comes time for a customer to actually implement against your API, you need the space to tweak the API to meet their needs, and/or to build the API out for their requirements in real-time. If that API is public, it’s much harder to change it on a whim, or roll in a new set of secret fields that you don’t want any other customers to know about. So it’s important to keep an API hidden so you can build exactly the right custom, standardized API for each customer.
Reason #2: Innovative APIs
Innovation is so important for a company, and your API is a key area for innovation. Using unique document structures, url schemes, request/response formats, security protocols (more on that later), etc., are all low hanging fruit to show how innovative your engineering group is. But if you invest all that time into innovation, do you want anyone who happens to stumble across your API to be able to copy it? Your awesome SOAP namespace design, right out there for anyone to rip it off as their own? Of course not: keeping your API private protects you from copy cats and lets you put a nice fat NDA in front of anyone before they get to see your IP.
Reason #3: Limiting Usage
One thing that’s really tough about APIs is that once a bunch of customers start using them you can’t change them as easily. Heavy usage kills innovation, increases time spend on support, and is a productivity drag. By putting your API behind a high-touch sales process you ensure that only the really serious customers ever get to see it, much less use it. There’s a good chance it won’t even get used at all, leaving maximum room for even more innovation. And that’s what really matters, right?
Reason #4: Bots
The web is crawling with bots that are clicking things, scraping content, and letting just anyone search out information. Multiple search engines will web crawl your publicly available API docs, scraping your content and loading down your site with all kinds of traffic it shouldn’t have to handle. The only way to protect your API documentation from bots is to hide it behind a very carefully protected password.
Reason #5: Security
Saving the most important reason for last, we have security. The best way to keep your users safe is to innovate in security protocols by having a really unique way of authenticating clients and authorizing calls to your API. If you then publish your API docs publicly, your security approach will be open to hackers who will read about it and use the features you built into the protocol against you. Only letting legitimate customers get access to the docs protects you from nefarious behavior and ensures only legitimate uses will ever be made of your API.
Given all of these very compelling reasons, it’s really hard to understand why anyone publishes their API publicly. The consequences of making it easy for engineers to review and use API documentation are dire, and it’s important to stand firm and resist this fleeting fad. And this is only the tip of the iceberg! You probably have your own examples of why public API documentation is problematic. So, please tweet @spreedly with your great reasons to hide API documentation behind layers of salespeople, webinars, and password protected PDFs — we’ll be sure to retweet the best ones.
Originally published at blog.spreedly.com on April 13, 2017.