Why would anyone do that?
Debugging is boring. Wouldn’t you
rather appeal to customers who write
bug-free code on the first try?
To really show disdain for your customers, use a proprietary protocol so
that language support is limited to the
client libraries you provide, preferably
as binary blobs that are never updated.
If you design it carefully, a proprietary
protocol can be difficult to understand
and impossible to debug, too.
Alternatively, you can use SOAP
(Simple Object Access Protocol). According to Wikipedia, SOAP “can be
bloated and overly verbose, making it
bandwidth-hungry and slow. It is also
based on XML, making it expensive to
parse and manipulate—especially on
mobile or embedded clients” (https://
like a win-win!
Technique #6: Permit
Only One API Key
One of my favorite ways to show dis-
dain for a customer is to permit only
one API key at a time. Anything you can
do to make the customer’s operations
full of toil and cognitive load says, “I
don’t care about you.”
An API key is basically a password that
identifies and authenticates a customer.
You have only one password for your
email account; why would you need more
than one? That would be weird, right?
Eventually, customers will need
to change, or “rotate,” their API key.
Maybe it was leaked. Maybe an employee left the company and has a
copy of the key. Maybe they just need
to rotate the key yearly as part of their
Here’s the hilarious part. If you permit only one API key at a time, you’ve
created a catch- 22 situation. Customers can’t change the API key on the
server, because the clients will lose access until they’ve been updated, too.
They can’t change the clients first because the server won’t yet know about
the new API key. If there are multiple
clients, then you’re basically expecting your customers to flash-cut all
clients at the exact same time. Basic
physics says that can’t happen. Even
if it could happen, there’s no way to
canary the new key; you’ve added deployment risk and complexity where
nobody would have expected.
Remember when mobile phone
companies charged $100 for a $2 data
cable? Why can’t APIs be like that?
You have the potential to inflict a surcharge on anyone who dares to want
to make efficient use of your product.
Don’t squander this opportunity!
It is normal to charge for your service, or include API access only with the
enterprise edition. In fact, that’s a good
way to keep out spammers or others
who would abuse the service.
But that’s not what I’m talking
about here. I mean you should charge a
lot extra for the API. A. Lot. Of. Money.
Make it a revenue stream instead of
a way to encourage people to use your
product. Make API access so expensive
that the sales department thinks API
stands for additional profit incentive.
This is a lot easier for on-premises
software. There the SDK can be sold
separately, perhaps using an otherwise
unadvertised SKU. Require management approval, a blessing from the
pope, and a note from your mother.
Technique #4: Hide the API
Docs from Search Engines
Nothing says “We don’t actually want you
to use our API” like making your API documentation invisible to search engines.
The “build, run, debug” cycle of decades
ago has been replaced by “run, crash,
Google, fix.” If your API documentation
doesn’t appear in search engines, you’ve
sent your customers back to the old days.
Luckily, this can be easily done by
putting the documentation behind a
login screen. If Google can’t crawl it,
it can’t index it. Googling for answers
about your API will be impossible.
Requiring some kind of registration
or login to access your API documentation also prevents your competition
from examining your API and learning from it. No competitors have ever
thought to register using their home
address, or to share a password from a
friend, right? Never. They are not that
smart. It could never possibly happen.
You would certainly never do that, so
why would they?
If your management refuses to
hide documentation behind a login,
consider making your documentation a PDF file. This is nearly as frustrating. Most search engines can peer
into PDFs, but not if you print the documentation and scan in each page as
a bitmap. If search engines OCR such
documents, just reformat your text in
columns, or tilt the document when
you scan it. Be strong, young soldier!
With a little elbow grease and a lot of
moxie, you can stay one step ahead of
anyone who wants to make it easy to
access your documentation.
Technique #5: Use a Terrible Protocol
Many APIs use JSON:API (https://jsona-
pi.org) or JSON-RPC (www.jsonrpc.
org). They are lightweight, easy to use,
and easy to debug.
What does your API reveal about your feelings toward your customers?
Technique Treat customers with disdain Show customers love
1 Don’t have an API Have an API
2 Make signups difficult, users must justify
3 Exorbitant fees for the privilege of API
Enable API access for free or as part
of an “enterprise-level” package
4 API documentation behind login page or
otherwise hidden from search engines
API documentation freely accessible
and referenced by public search engines
5 Use a proprietary or terrible protocol Use an industry-standard protocol such
as JSON:API or gRPC ( https://grpc.io)
6 Permit only one API key Permit multiple API keys for easy rotation
7 Tempt fate by maintaining documentation
Keep documentation in sync
with code using automated systems
such as Swagger or gRPC
8 Ignore the infrastructure as code (IaC)
Make IaC a top priority: Provide officially
supported modules for Terraform, Chef,
Puppet, Chocolatey, and similar systems
Design APIs to be idempotent