On Tue, Apr 16, 2013 at 11:50 PM, Tyler Romeo <[email protected]> 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. _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
