API V2 Beta Documentation

[viet]

Purpose

• Update the API to meet the needs of both the company and our users.
• Optimize the API to return only what is necessary.
• Set the API up for easier versioning, allowing for more frequent updates while maintaining older versions for reliability.

Disclaimer

Expect breaking changes until the framework has been solidified. Keep in mind this is an beta! There may be more endpoints to come and the structure of API results can be changed dramatically before we release the 2.0 version.

Documentation

https://docs.api.wanikani.com

Mailing list

Get all the API updates by joining our API specific mailing list found here.

Sunsetting V1

When V2 moves out of alpha/beta and becomes official we plan on sunsetting API V1. We have not decided on the length of this period, but are leaning towards four months.

[rfindley]

A little light evening reading…

[ccookf]

So is the new API key setup always going to be a 36 char string in the format {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}? I’m just a tad lazy…

Also, will the API ever open up additional information outside of user specific data? Not too long ago there was a guy asking about prerequisites and I ended up scraping parts of speech for a different experiment.

[viet]

Also, will the API ever open up additional information outside of user specific data? Not too long ago there was a guy asking about prerequisites and I ended up scraping parts of speech for a different experiment.

The subject endpoint provides the information you listed.

[ccookf]

I am blind. Sorry for missing that ><

[viet]

So is the new API key setup always going to be a 36 char string in the format {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}? I’m just a tad lazy…

Pretty much. It is basically UUID.

[viet]

Oops. Forgot to add more text.

API V2 Alpha is live. Read the doc. Play around with it. Give us some feedback.

And if anyone knows how to reduce SSL handshake times, we would like to pick your brain

[bladepoint]

Do you have an OpenAPI specification document you can share?

[AnimeCanuck]

Because it says that we can get it (or change to it?) in the settings… I have a few basic questions.

1) So I expect this new API will mean that any old userscripts or community-made apps (like mobile ones) that have no support will no longer work. (When/if we switch to V2, Alpha or otherwise.) Correct?

2) Are we able to get this new V2 Alpha API to “play around with” and help test such scripts and/or changes, while keeping our V1 API keys? (So that older user scripts continue to work and/or in case something breaks, etc…?)

Glad to see that rfindley has already noticed this post. I was going to ping him if he hadn’t.

EDIT: Read the rest of the OP. Interesting to know about the sunsetting in advance… I’ll also be curious to see how this new API affects the idigtech stats page, and some other specific scripts (like @xMunch’s Ultimate Reorder). Hmm…

Viet, you and the other devs have been busy bees!!! (Or maybe not, since you admit to copy-paste-modify from Stripe (whomever they are). XD ^_~) Thank you for keeping us updated and informed (even if I don’t fully understand everything, and this will probably break my mobile app by the end of the year.)

EDIT 2: Above questions @viet . Especially #2.

[seanblue]

and some other specific scripts (like @xMunch’s Ultimate Reorder)

Since I’ve been digging through xMunch’s script the last few days, I’m pretty sure it scrapes the UI and doesn’t actually make API calls.

[AnimeCanuck]

Oh, that’s cool to know!

However, I know most of rfindley’s stuff that I use does… Ultimate Timeline [Basic Edition] for sure, Dashboard Progress Plus, Self-Study Quiz Edition, and others. But I guess I could be wrong on those other ones other than Timeline…???

[carlostdev]

Thank you, thank you, thank you for that!

I’m planning to start a personal project that required such data and was starting to think about ways to scrape the requirements from the website, LOL.

Looking forward to this.

[jprspereira]

I understood absolutely nothing.

Keep doing what you’re doing. You seem like cool people. I trust you

[seanblue]

To page through the results, send additional requests with a page parameter.

I don’t know how this will be used, so let me know if my question is off base. Is there a use case where items actually get inserted (not just changed data for static items), such that two requests for back to back pages could actually miss an item or have a duplicate item returned? Basically some information is in position 250, but then something else is inserted there so when page two is requested, the new 250 is missed and the old 250 is returned again in position 251.

[viet]

It is ordered by ID, so the only time this shifting would be an issue if a resource gets deleted. It rarely happens. Leverage the updated_after filter or data_updated_at key if insertion of new resources is a concern.

The paging exists to control the file size of the responses.

---

One flow to go about getting the information is to hit up the collections to get all resources and cache them.

Then use the updated_after on future requests to pull in updated resources and update your cache.

On V1 there wasn’t a good way to get recently updated data. You would have to grab the full collection and check for data changes.

[ccookf]

Just curious, but will the ID’s ever be affected by content changes in the future?
Edit: to clarify, it looks like there’s a general arrangement of radicals -> kanji -> vocab, even if a bit jumbled. If say a radical was added would that get inserted, or added to the end?

[viet]

IDs for subjects will never change. They stay constant.

IDs for assignments, review_statistics, and study_materials also stay constant unless a user resets; resets triggers deletion of resources (at the moment), so new ones will regenerate as the user begins to unlock them.

[viet]

If say a radical was added would that get inserted, or added to the end?

Like a new radical subject was added? If you hit the /subjects endpoint it will show up at the end since the default order is by :id. And every new resource creation is just an incremented id.

If you want to check to see if new resources have been added just use the updated_after filter and use the timestamp of the last time you made the request at the collection endpoint. Anytime data is changed on the resource the data_updated_at is updated. updated_after filters based on that field and a recently inserted item will have a recent data_updated_at timestamp.

[viet]

1. So I expect this new API will mean that any old userscripts or community-made apps (like mobile ones) that have no support will no longer work. (When/if we switch to V2, Alpha or otherwise.) Correct?
2. Are we able to get this new V2 Alpha API to “play around with” and help test such scripts and/or changes, while keeping our V1 API keys? (So that older user scripts continue to work and/or in case something breaks, etc…?)

1. Correct.

2. V2 alpha is live now. Both V1 and V2 are active at the same time right now. Check the OP for instructions. Getting the authorization requires a little knowledge of request headers.