They say the secret to great comedy
is timing. Imagine the hilarity of a customer using your product for a year before realizing key rotation is logistically
Hilarity? Or disdain. Whatever.
Some companies do not understand comedy, or how to show disdain
for their customers. They permit customers to add a new key on the server,
slowly roll out the new key to all clients,
testing along the way, then deactivate
the old key. Gross!
Technique #7: Maintain
As your API evolves it is possible for
the API and the documentation to get
out of sync. Nothing says “I don’t care
about my users” like building a system
that encourages this kind of error.
Or you can go for the trifecta: an API
that is out of sync with the documentation, which is out of sync with the client
libraries you provide.
Sure, there are systems such as
Swagger ( https://swagger.io/tools/open-source/) and gRPC ( www.grpc.io) that
let you define APIs and their documentation in one place, then automatically
generate the documentation, server
stubs, client SDK bindings in multiple
languages, and so on. But what’s the fun
in doing work once and letting computers generate all the downstream artifacts you need for free? Consistency is
Technique #8: Ignore
The IaC Revolution
The ability to treat infrastructure as
code (IaC) is becoming a top priority for
operational teams. It not only makes
operations easier, more testable, and
more reliable, but also paves the path
to security compliance best practices
required by the likes of SOC2 (Service
Organization Controls) and PCI (
payment card industry).
Some companies waste their time
making it easy for customers to do this.
They provide officially supported modules for accessing their services from
Terraform, Ansible, Chef, Puppet,
and similar systems. They make their
client-side software easy to consume
by hosting repositories for multiple
Linux distributions, and they provide
a Chocolatey feed for easy installation
It’s much simpler to ignore all of
these technologies and hope that the
open-source community will provide.
Yes, this may result in a confusing array
of incompatible options, but you can
trumpet the benefits of “user choice.”
Technique #9: Don’t Be Idempotent
I’ve saved the nerdiest technique for last.
An operation is idempotent if performing it multiple times yields the same
result as performing it exactly once.
Suppose there’s an API call that creates a virtual machine (VM). If this API
call is idempotent, the first time we call
it the VM is created. The second time it
is called the system detects that the VM
already exists and simply returns without error. If this API call is non-idempotent, calling it 10 times will result in
10 VMs being created. (Note: the opposite of idempotent isn’t potent.)
Similarly, an idempotent delete
call will remove the object; subsequent
calls will quietly do nothing and return a success status code. If the call
were non-idempotent, the second
call would return a “not found” error,
which would confuse the developers
and potentially make them question
the meaning of existence.
Why would anyone issueo the same
API call more than once? When dealing with RPCs (remote procedure
calls), the response may be success,
failure, or no reply at all. If you don’t
hear back from the server, you have to
retry the request.
With an idempotent protocol you can
simply resend the request. With a non-idempotent protocol, every action must
be followed by code that discovers the
current state and does the right thing to
recover. Putting all that recovery logic in
the client is a layering violation.
In the VM example, you would
have to query the inventory and see
if the VM you asked to create exists.
If it does exist, you must make sure
it was created properly or is in a good
state. If it is in a bad state, you repair
it or delete it and start over. The list of
potential conditions and edge cases
goes on and on.
That was a simple example. Recovery from other API calls can be
even more complex. The attempts to
recover from failures may also fail.
Now you are faced with an infinitely
recursive world of failures, failed re-
actually want you
to use our API”