1) What is the best way to ask for an API key from the callers?
I don’t have a huge opinion on this. If it were me, I’d probably just have them pass it in the headers since it seems more like meta-data surrounding the request and not really part of the specific REST resource being accessed (thus it would be annoying to have it in the URI) and you can’t count on their being a request body if it is a GET.
2) If a particular API call only supports GET method, then should I be checking for the HTTP method in the headers and rejecting any other methods but GET? Or is it OK to let any methods come in?
ColdBox already supports this. Check into the AllowedMethods property of handlers:
this.allowedMethods = {
delete = "POST,DELETE"
list = "GET"
};
Also, if you’re using custom routes, check out the API docs for addRoute(). You can specify HTTP verbs for different actions
"action - The action in a handler to execute if a pattern is matched. This can also be a structure or JSON structured based on the HTTP method(GET,POST,PUT,DELETE). ex: {GET:‘show’, PUT:‘update’, DELETE:‘delete’, POST:‘save’}"
So, basically http://api.com/user/100 could be your endpoint, and the HTTP method you use can cause a different action in the handler to be called.
3) In general, what are the best practices to authenticate an API call? A lot of API’s nowadays do this via oAuth and I am not sure I am willing to go through the complexity of implementing that if there is an easier way. I found this article http://www.thebuzzmedia.com/designing-a-secure-rest-api-without-oauth-authentication/ but your thoughts would be much appreciated.
That’s an interesting article. What’s funny is how pretty much every attempt at authenticating boils down to the same process. If you want my suggestion, make your entire API require HTTPS and have them slap their credentials right there in every request. Most of the rigor of other APIs’ authentication pieces seem to be related to being able to send them plain text over the Internet. HTTPS pretty much makes that a non-issue.
Thanks!
~Brad