API V2 Beta Documentation

[ccookf]

Got it. I made an incorrect assumption about the nature of assignments, hence the confusion. Everything was pretty easy to get into and use, but I will concede I am an idiot that incorrectly formatted the header at least five times.

Last, completely irrelevant question: how are you guys liking Cowboy? My inner child gets a little excited whenever I read that in the headers and my inner weeb is enjoying the homepage.

Edit: Before anyone else makes the same stupid mistakes I did
headers: { ‘Authorization’: ‘Token token={’ + v2key + ‘}’ }

[rfindley]

Upon first pass read-through, this looks great! I’ll compare it against all my scripts and the stats site to see if there are any potential missing use-cases.

Two things I didn’t see that would be useful (unless I overlooked them?):

• Vocab audio links
• Vocab example sentences

Any plans for those?

Also, totally out of nerdy curiosity: do you plan to use document records for responses that are static? i.e. pre-composed JSON objects stored in the database?

[viet]

@rfindley

Two things I didn’t see that would be useful (unless I overlooked them?):

• Vocab audio links
• Vocab example sentences

Any plans for those?

We are still discussing about whether or not to include those two

@rfindley

Also, totally out of nerdy curiosity: do you plan to use document records for responses that are static? i.e. pre-composed JSON objects stored in the database?

If it gives us faster response, sure Everything is fairly basic right now; serialized results get cached to memcache and the HTTP headers modified data check on requests. Just wanted to get out a minimum product first for feedback and see how it responds in its current iteration. We do plan on optimizing it depending on the results we see.

[viet]

We’ll get proper documentation going once we have settled on the API (i.e. closer to the final product).

[viet]

@ccookf

Last, completely irrelevant question: how are you guys liking Cowboy? My inner child gets a little excited whenever I read that in the headers and my inner weeb is enjoying the homepage.

No complaints Heroku seems to like it, so that is what we have to use, haha.

[AnimeCanuck]

Iiinteresting. But good to know. (Hooray both!) Thanks.

@viet

Getting the authorization requires a little knowledge of request headers.

I will have to try that, when the time is right… (I think I’m looking at you, @rfindley… and @seanblue .) I may also need a walkthrough from one of those two when they’re ready. Your sentence or two about it in the OP made it sound easy, but now that you’ve said that…)

Again, thanks, Viet! ^^

[StellaTerra]

Also, totally out of nerdy curiosity…

Wouldn’t that be the job of a CDN, like cloudfront or somesuch? If I were designing it, I would keep all static content out of the response, and have the client grab it once, store it locally, and access it for everything. Slimsdown the API a bunch, and potentially makes the whole thing more responsive, as well as reducing bandwidth and server cycles.

[AnimeCanuck]

@StellaTerra

Wouldn’t that be the job of a CDN, like cloudfront or somesuch?

Oh. And all this time, I thought that meant “Canadian”… and I thought websites were being re-routed to or through Canadian versions before coming to me… especially since we have region-specific content laws nowadays… Wow… You learn something new… ^_^;

[viet]

@StellaTerra

If I were designing it, I would keep all static content out of the response, and have the client grab it once, store it locally, and access it for everything. Slimsdown the API a bunch, and potentially makes the whole thing more responsive, as well as reducing bandwidth and server cycles.

We designed V2 with this in mind The subjects endpoint is the static content. The other endpoints contain the user specific content which update more frequently.

[rfindley]

@StellaTerra

Wouldn’t that be the job of a CDN, like cloudfront or somesuch?

Since no data is truly static, it’s important to choose a cache duration that makes sense for your needs. For example, if it’s important that updates roll out quickly, a shorter cache duration is necessary.

Either way, for every query that reaches the server (as opposed to being retrieved from cache), the server has to send out a JSON object. You can either generate the JSON object every time, or store the pre-computed JSON object in a document database. The latter will generally reduce load on a server, though you’d probably want to evaluate the savings before taking the time to implement it.

[rfindley]

@viet

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

Well, there’s Session Resumption and OCSP Stapling, if your web server supports them. It looks like neither are enabled on WK.

OCSP Stapling is where the server periodically queries the top-level server in the certificate chain, and forwards that response to each client that connects, so the client doesn’t have to check the top-level server themselves. (Digital signatures ensure that the forwarded response is trustworthy).

Session Resumption caches the TLS session state for a period of time. If the user reconnects within that time, it eliminates half of the handshaking (which normally takes two round-trips). But this needs to be done right to prevent compromising forward secrecy (i.e. keys need to be rotated daily, which may not be the default behavior).

[xMunch]

While you’re doing back-end API stuff would you mind including level in the queue requests? Would help us both out if you did . I could finally take out that wretched data scraper from my userscript.

[viet]

What endpoint are you talking about specifically?

[xMunch]

/review/queue and /lesson/queue
I know it’s not in the API section, but should be an easy change nonetheless.

[viet]

What you see is what you get with those internal endpoints, I am afraid.

[rfindley]

As a wish-list item, I would be interested in looking up individual items by name:

• /api/v2/subjects?type=radical&name=raptor-cage
• /api/v2/subjects?type=kanji&name=年
• /api/v2/subjects?type=vocabulary&name=漢字

Currently, the only way to do that is by parsing the HTML of urls like:

https://www.wanikani.com/radicals/raptor-cage

and I don’t think there’s an item ID on those pages that can be used to refer back to the API.

[Subversity]

@rfindley

Vocab audio links
Vocab example sentences

We’ve had many many requests for the audio but I’ve had to say no, that we won’t scrape the content because you haven’t decided to expose it publically. Which is totally a fair call - but… it would indeed make many WKers very happy in their reverse revision ^^

No specific thoughts from me on the API structure other than a hearty
I’ll leave feedback to @Tadgh11

[Swarley01]

@viet it looks like the radical image urls are coming back without the slug injected (e.g. https://cdn.wanikani.com/subjects/images/8761-:slug.png).

Also, the key for that value is “character_svg_url” but it is returning a png. I think to have the best overall support, keeping an asset reference as png is a good idea. SVG + iOS, for example is not a great combination. If you guys definitely want to include an SVG asset reference, maybe “character_svg_url” is instead:

"character_images": [
    {content_type: "image/png", url: ".../image-:slug.png"},
    {content_type: "image/svg+xml", url: ".../image-:slug.svg"}
]

[valeth]

@viet

data: {
level: :integer,
created_at: :date,
character: :string_or_null,
character_svg_url: :string_or_null,
meanings: :array_of_objects
}

@viet
Are you replacing the custom radical images on the website with svg images, or is this just for the API?

[viet]

As stated in the documentation it is a placeholder…

We are going to be providing actual SVGs, at least thats the plan.