API Feedback

Hi FliesLikeABrick,

I took a brief look at your API design in the wiki and had a couple of questions/feedback. I've done a bunch of RESTful API development in the past, so I figured you wouldn't mind the technical feedback.

1. How will you be versioning the API when you plan on deploying it?
   • I tend to like the explicit nature of having the version in the API (like how stackoverflow does it, e.g., /api/1.0/players).
   • However, since you already have the URI structure down, it looks like a custom header might be a a good option (e.g. X-kag-api-version: 1.0). If you go this route, just please make sure it's documented - i once encounters some API doc that required this header but never documented it, which did not make for a fun programming experience. :)
2. Will you eventually implement developer API tokens?
   • I ask this because I recently went through some API authentication design work and had some discussion around why one would want to implement API tokens. My team and I basically came down to API tokens being important for when the server admins want to track and control the people that are accessing the API. For example, twitter has a limit of 100,000 copies of an API token being used in the wild (i.e. 100k separate devices use that token for a custom twitter client). The API token management gives Twitter the ability to monitor the applications that use the token since many copies of an app may exist and throttle the token if it reaches a certain limit. I saw you mention in the wiki that throttling may occur via IPs, but I wouldn't be surprised if a DDOS attack or viral growth of an API consumer might affect your servers.

Anyways, those are just my 2 cents - from what I see in the forums and what I've read in the docs, you're doing all the right stuff so far when it comes to the API and it looks like you're the only guy doing it, which makes it understandable as to why the questions above may not be fleshed out at all yet.
Thanks!

 

Maybe something like Accept/Content-type application/vnd.thd.kagapi-v2+json or whatever, but you might have issues modifying Accept/Content-type for directly pulled things using javascript on the client end

 

Anything that's "Non-Standard", would be foreign therefore you would have to entirely do it different. If I'm understanding what you are saying I see that you are talking about JavaScript.

 

Code:

var client = new XMLHttpRequest();
client.open('GET', 'url');
client.setRequestHeader('X-KAG-API-Version', '1');