On Tue, Apr 16, 2013 at 11:50 PM, Tyler Romeo tylerromeo@gmail.com wrote:
Found this interesting articles on designing an API for what it's worth. Thought some people my find it interesting.
Some thoughts:
#2: HTTP Basic authentication is simple, but not particularly secure.
#3, #4, #6, #12, #18, #21: It depends on your API design. Are you using HTTP as a transport (which is what the MediaWiki API does) or is HTTP your API (e.g. REST)?
#7, #8, #16, #17: Easier said than done, unless you're writing your own webserver, or hooking into the existing webserver at a deep level (which may not even be possible).
#9: There's no generic mechanism in HTTP to compress the request body; although some servers may support such a thing (if configured to do so), it's not standardized. "Accept-Encoding" tells the server which encodings it is allowed to use for the response body, and "Content-Encoding" indicates which were used for the response. And this too is often handled automatically at a lower level than you're likely to care much about.
#24: The downside being that then you have to maintain multiple different versions of your API. If you are doing this, it would be best to have a clear policy on removing old versions so you're not stuck supporting them forever. And if the underlying code or data structure has to change in a way that makes something prohibitive or impossible in the old version of the API, you're still stuck breaking things.
#26: Since he mentions REST several times (e.g. #31), I note that I've yet to see a method for really combining REST and bulk operations beyond something akin to "rm -rf".
#34: "If your API accepts the same authentication configuration that your interactive users use", not quite. Try "If whatever your API uses for auth is automatically sent by a browser" whether you intend it to be interactive or not.
#40: OTOH, hand-written documentation easily gets out of date. Having both hand-written and automatically-generated is nice.