Kindle Notes & Highlights
API keys are similar to user names and passwords in that they consist of a public access key that identifies the system interacting with the API and a shared secret between the consuming system and the API provider. API keys have a number of advantages. First, they can be much stronger than a user name/password since no one has to remember them. Typically, API keys are long random strings like an access key of FMKPVBVBCKUZJETXXRVP with a secret key of C5eTeKuXtnibcfm+LNYsIiMsSaaQ6xAFTpQtH0kW. The second advantage to API keys is that they don’t identify users; they identify systems optionally
...more
Request signing almost always goes hand-in-hand with API keys as user passwords tend not to have enough entropy to serve as good request signing keys. The chief advantage of request signing is that it never sends sensitive authentication data over the wire. Consequently, you can run a request signing API over plaintext. When done right, you don’t even have to worry about man-in-the-middle attacks. Finally, when combined with a nonce, you can also prevent replay attacks.
The downside to request signing is that it adds expensive cryptographic operations to every single HTTP request against a protected resource. The more secure you make the signing algorithm, the more expensive the signing process is. The key to a solid request signing algorithm is to minimize the possibility of collisions across different requests.
In particular, if you aren’t concerned about supporting non-SSL traffic, then #3 is good enough. If you want to support non-SSL traffic or if you don’t want to install server certificates on the clients, you must use #2.
Is there any valid use case these days that absolutely requires no server certs or plaintext communications? If you own / control the host server, what would stop you from doing this? If you don’t have admin control, what 3rd party host are you using that doesn’t have SSL?!
And pedantically, isn’t everything TLS these days, not SSL? Does anyone care? Should do irrelevant factoids from “the careless pedant” on Twitter
when you build a RESTful API, you should never break existing client code. Really, never. You don’t deprecate. You find a way to support that old client.
How feasible is this in the real world? What about retiring old versions / features that are no longer supported? Or bug-fixes / security patches that require breaking changes that invalidate the original version?
The negotiating of the version of the representation is really more like representation negotiation—in other words, it is a function of the headers. Indicating versioning through query parameters also gets around my identification concerns, but I feel it’s an abuse of query parameters and it creates a risk of query parameter conflict. First, I believe the role of query parameters in a RESTful API are to constrain a search or a “directory” listing. They should not be used to convey other kinds of information. Second, when you pick the name of your version query parameter, you must be certain
...more
version management for libraries has never worked particularly well. As the world becomes entirely API-driven, we have to do away with the notion of elegant deprecation of APIs. There’s never really been any such thing as elegant deprecation anyways.
Interesting debate to be had here
The problem you face as a successful API designer is that you will have so many different interests consuming your API with software written against different versions of that API. Each of those systems may vary in their ability to change just because your system has changed. In short, you can’t expect every single one of your API’s consumers to keep up with every (or even any) API updates. In addition, you can’t break their code during your upgrades.
What. Why would you continue sending unencrypted sensitive data after discovering the vulnerability? Surely security fixes are allowed to make breaking changes.
Many times when you are responding against old version request, you may have to construct alternative logic that mimics the old way things worked. The hardest situation to handle is when you completely remove functionality from the system. Hopefully, this scenario is quite rare. There are a number of ways in which you can deal with it: • You can make the client call a NO-OP (the system just does nothing) • You can attempt to execute some logic aligned with the original intent • You can issue an error and break the client code (this represents a design flaw)
Clearly running an alternate method is the best option, but if the operations were equivalent you wouldn’t have needed a new version. This just seems to idealistic. A no-op or an error seem like the only real options, and calling them a design flaw seems unrealistic as well. Needs change, systems change.
The one thing you don’t want clients doing is “hard coding” any expectations of what APIs are synchronous and what APIs are asynchronous. In other words, someone writing to the enStratus API should not think “the POST Server API is asynchronous, but the POST Firewall API is synchronous”. They should instead build their clients to look at the status code returned from the POST. If it is a 202, the client should expect a Job resource in the body representing an asynchronous operation. If it is a 201 (Created), the client should look for identifying information about the created object in the
...more
Aggressive rate limiting is generally a sign of a weak physical infrastructure insufficient for supporting your API consumer needs. As the API provider, you are in a poor position to judge what constitutes valid use of your API. Punishing your users by breaking their code isn’t the right way to deal with the situation.
Just... wow. Yes being too restrictive in limiting is a sign that you’re stretching your hardware too far, but saying that you can’t decide how your api should be used seems extreme.
