1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.
  2. Hey Guest, is it this your first time on the forums?

    Visit the Beginner's Box

    Introduce yourself, read some of the ins and outs of the community, access to useful links and information.

    Dismiss Notice

API Feedback

Discussion in 'Community Dev Corner' started by strife25, Nov 12, 2012.

Mods: Downburst, Mazey
  1. strife25

    strife25 Catapult Fodder

    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.
    ParaLogia likes this.
  2. FliesLikeABrick

    FliesLikeABrick THD Team THD Team Administrator Global Moderator

    Hi strife - - I have been traveling a lot this month and only now saw your thread.

    When I get around to properly versioning the API, I will likely do it with the Accept/Content-Type headers. If the request's Accept header does not list any kag-api/0.1 or however I choose to format it, it will default to the last non-versioned version of the API. If it lists one or more versions of the API, the latest one supported by the API server instance will be used. The version used would be indicated by the Content-Type of the response. Currently the content type is application/json or similar, so this would replace that. (edit: yes, or a custom header, as you indicated. That was the other option I've considered)

    Yes I plan on having developer API tokens when the time comes that permissions need to be granted to certain site/web/application developers who use SSO. It would also help with some scaling/abuse issues as you indicated, though so far that has not been an issue and therefore lower priority than some other projects.

    I haven't 100% fleshed out those ideas, as you noticed, but your input/feedback is valuable. When the time comes that I am implementing one or both of these, I will definitely come back to read your comments as I work on the design.
  3. Teemo

    Teemo T͔̕e͖͚̖̯̩̪͙͝e͡m̖o̤̪͘ Forum Moderator Donator Tester

    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
  4. FliesLikeABrick

    FliesLikeABrick THD Team THD Team Administrator Global Moderator

    Can JS add non-standard headers, like if I used X-KAG-API-Version?
  5. splaph

    splaph Catapult Fodder

    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.
  6. Teemo

    Teemo T͔̕e͖͚̖̯̩̪͙͝e͡m̖o̤̪͘ Forum Moderator Donator Tester

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