On Tue, Apr 16, 2013 at 11:50 PM, Tyler Romeo <tylerromeo(a)gmail.com> wrote:
Found this interesting articles on designing an API
for what it's worth.
Thought some people my find it interesting.
http://mathieu.fenniak.net/the-api-checklist/
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.