Ok.. I'm open to this. I think the timeframes you have suggested are good. Anyone else has opinions on this?
I'd say also number of reviews starting at the next review time, within 5min/10min/30min/1hr for example.
Or perhaps pass in the total timeframe (say 1day) plus an interval (say 5min) and it would return #reviews in 5min, #reviews in 10min, etc up to #reviews in 23:55 and #reviews in 24:00. Might want to put limits on the minimum interval and maximum timeframe to prevent abuse, but something like that would allow an app to approximate the "future review" bubbles that someone mocked up a few weeks ago on one of the forum topics.
Or go the opposite way and just return the timings for the next X reviews (100, 200, whatever is appropriate without munging the server resources.) Could be used in a similar manner but would be much more accurate (at least for the amount of reviews it returns.)
Of course a lot of it depends on how much data you're willing to give out ;)
Regarding the email addresses, you could always return the gravatar hash in the user api call. It doesn't expose the email directly and the hashes are public anyway, so nobody can complain.
This is a good idea if there's an issue with emails being available publicly.
I knew the API will be public but I thought you were only able to return user details (like an email address) if you had the API key of a user? Not that I'm so bothered about the email address, just throwing an idea out there for the sake of it :)
For instance put the API controllers in app/controllers/api/v1/ and namespace them "class Api::V1::ApiController < ActionController::Base"
This means if/when you need to drastically change the API you just make an app/controllers/api/v2/
Yes this means duplicating API code, but it stops you breaking anything relying on V1 of the API and you can gracefully move people away from the old versions.
It also means you can add fixes/changes to old versions very easily because the code is completely separate.
There may be more elegant ways to version it but this is how I handled it for a small API
Your API routes would also contain the version e.g. /api/v1/users
This makes using json a lot easier and allows you to expose only the attributes you want to
You can also present/decorate the data here, so converting dates into different formats etc
If you have user roles/rights you can restrict attributes here too
I would namespace these as well since between api versions you might change/remove/add attributes in a serializer. So app/serializers/api/v1/api_serializer.rb would contain "class Api::V1::ApiSerializer < ActiveModel::Serializer"
Rate limit the amount of calls that can be done by a key/IP
Stops a rogue app eating up resources like a cookie monster
Excellent technical points from an API design perspective. I think the point about the versioning to prevent breakages is very important.
If I read this right, it looks like all the developer’s app requests are made using the same token regardless of who was the one that requested the data. While rather standard my concern with this api is that it’s more appropriate for server setups than clients. It just doesn’t feel right in an open source project (which could vary from a browser extension to a OS specific plugin).
However, coming up with an alternate authentication system without exposing the users credentials is a time consuming affair, but I just wanted to share my thoughts.
If I read this right, it looks like all the developer's app requests are made using the same token regardless of who was the one that requested the data. While rather standard my concern with this api is that it's more appropriate for server setups than clients. It just doesn't feel right in an open source project (which could vary from a browser extension to a OS specific plugin).
However, coming up with an alternate authentication system without exposing the users credentials is a time consuming affair, but I just wanted to share my thoughts.
Thanks for being so open about this.
Argh, nevermind, I see that these are user tokens not developer tokens.
Is this seconds until next review or the epoch time of the next review? In the last case I'd suggest using a long so you won't hit Y2038 problems :)
Epoch time of the next review. So it'll be up to the third party app if they want it in distance time or a date. If a review is available now, it'll output a date before the current timedate. It should be easy on the developers end to write the logic for this.
What about the progression information? Number of radicals and number of kanji to know (and currently known) before reaching new level. I look at that more than my total number of guru’d items.
Maybe it is considered content, but the wanted list (and a list with recently wrong answered reviews) would also be amazing to have. I would create an app to display it on my android phone on my home screen, remembering me the stuff what i should learn. The name + type (vocab/kanji/radical) would be enough for the API. It is enough to create a link to the site with all other information :).
What about the progression information? Number of radicals and number of kanji to know (and currently known) before reaching new level. I look at that more than my total number of guru'd items.
Maybe it is considered content, but the wanted list (and a list with recently wrong answered reviews) would also be amazing to have. I would create an app to display it on my android phone on my home screen, remembering me the stuff what i should learn. The name + type (vocab/kanji/radical) would be enough for the API. It is enough to create a link to the site with all other information :).
Progression information would be included. I just implemented today, so might as well open it. I could see the usefulness of adding a wanted list. May consider it.
This discussion is only relevant to the programmers out there. So if you aren't one of em, move along :)
Ok.. So I figured I might as well get the bulk of the API set up right now since I'm already tearing apart the backend.
What kind of information would you all like to access? Note that an API to the site content itself is closed at this time.
So here is what I'm thinking.. You can request the top level, and get the information in the bullets
Study Information
Number of lessons available (int)
Number of reviews available (int)
Time until next review (int, by epoch time)
SRS Counts
Apprentice
Radicals (int)
Kanji (int)
Vocabulary (int)
Total (int)
Guru
Radicals (int)
Kanji (int)
Vocabulary (int)
Total (int)
Master
Radicals (int)
Kanji (int)
Vocabulary (int)
Total (int)
Enlighten
Radicals (int)
Kanji (int)
Vocabulary (int)
Total (int)
Burned
Radicals (int)
Kanji (int)
Vocabulary (int)
Total (int)
Along with each request, you'll also get user information and additional messages (such as in the event the key doesn't match a user or some other error)
User Info
Username (string)
Level (int)
Message
Important messages, like errors or etc. Otherwise, nil/null/whatever.
Of course, you can also just request the user information by itself. If there is something else you all would like to access, I'm open to ideas.
Output will be an array list encoded as JSON.
Each user will get a unique generated key as an identification. A new key can be regenerated at any time, which voids the old key.
Accessing the information can be done via GET url request... Something in the structure of
This is my first time making something like this, so any suggestions/info etc would be welcomed :)
Also, I would like to get a Github organization going and consolidate/make open whatever projects you all are making. Of course, you can refuse to make open your project, but it'll be nice to get people involve and not have duplicate apps out there. Also would be easier to pass the buck if someone decides to not invest their time on said projects. I own the WaniKani organization :)
There is historical evidence that the great Allicrab that lives in the seas of the sky owns WaniKani.
Would be nice to get some information about the conditions for apps that use the api. Commercial/Non-Commercial/Open-Source?
I would like to create the Mac Notifier for free, of course. But maybe there is a possibility for a push notification iOS Version (=>Push Notification Server).
Out ofcuriosity, is their a policy allowing API developers to use WaniKani icons, artwork, or other images in software developed using the WaniKani API?
Thundyr said...
Out ofcuriosity, is their a policy allowing API developers to use WaniKani icons, artwork, or other images in software developed using the WaniKani API?
If the developer isn't charging for the software, then they are free to user the media. We'll be providing a zip of most of the material for any developer to use.
I’m going to use the API and an arduino board to build a robot who’s gonna check for reviews and notify me by koichi’s sexy voice and also he would kick my ass if I wouldn’t be reviewing right away
Looking very nice, also excellent documentation Could you also please add the hard limits on the responses? I noticed it’s about 100 (?) for the recent unlocks list, but asking the vocab of a couple of levels is no problem.
Incidentally, do the example responses on the API page count towards the 100 limit? (just curious haha)
Could you also please add the hard limits on the responses? I noticed it’s about 100 (?) for the recent unlocks list, but asking the vocab of a couple of levels is no problem.