API V2 Beta Documentation

Ah sorry, I posted here because I assumed you would have been informed about radical changes if there were any before creating the svg for all radicals :sweat_smile:.

Thanks for the response! :slight_smile:

No problem. I am informed of some details, but I am not involved in the low-level details; just donā€™t want to say things which may not be true :slight_smile:

1 Like

We have discuss a few solutions on how to deal with this. Seems the best option would be to employ soft deletes. All relevant objects will have a boolean field to signify if they are ā€œdeletedā€. By default both active and deleted states will be returned in the collection. An additional filter will be added to be explicit on what state the consumer wants.

Any thoughts on the above solution?

I like it. It allows us to know as soon as an item is deleted simply be checking a variable. I do worry however that if thereā€™s a few more variables that appear like this, the responses will be bloated :sweat_smile:.

Alternatively, you could have a separate endpoint for deleted resources. That way devs could just check it separately if itā€™s relevant to them.

either implementation would be very useful for Kaniwani. There are certainly some sync issues that revolve around data state on wanikani that would be solved with this.

This was one option we discussed, but it may get a bit burly. When a subject is deleted it cascades a deletion of a bunch of objects: assignments, review_statistics, study_materials, and reviews. Those deletions will also need to be recorded. And there is the fact the consumer must constantly read another endpoint.

The soft delete option seems to be the better option in our eyes since it works well with the updated_after filter on all relevant existing endpoints (updated_at field would get touched); no additional endpoint needs to be monitored and an additional data model is not required/needs to be maintained on our end. Also the data will remain intact, ā€œfrozenā€ so to speak.

We want to make sure we evaluate all options before making a decision and implemention. If there is something we are missing please let us know.

Iā€™m working on some really big radical/mnemonic changes, but when you change one radical it affects at least 10-30 other kanji. So itā€™s a very long process thatā€™s still in progress. There isnā€™t much to say yet, because when you touch this many items itā€™s impossible to give a realistic time frame. And I donā€™t want to make any promises I canā€™t keep.

4 Likes

Hey there, I have a question about the endpoints, will GET only be supported or will POST/PUT be supported on any of them? Sorry if this has already been answered already, I quickly searched the thread but couldnā€™t find anything related to this.

1 Like

Which endpoints do you have in mind?

1 Like

I think the ones I would be interested in are assignments (which I think corresponds to reviews in the UI) and whichever resource corresponds to lessons. We were discussing in another thread if we could create a command line client for WK using API v2 but obviously it would depend on POSTing a value to the server when an item has been reviewed (correctly or incorrectly) or an item lesson has been completed. Is this something that would be possible? Obviously it would only be available on items that are past their ā€œavailable atā€ date.

Essentially, there would need to be a POST method available on the lessons (not sure which resource this is, if any) and reviews (the assignments resource, I think), in order to create a custom client where you could do lessons and reviews.

1 Like

I found the previous documentation much more friendly (you know, examples and stuff)

1 Like

It sounds like eventually the documentation will be fleshed out some more once the API is out of alpha.

1 Like

I know i just meant it was nice to have at least an example. I havent done this in years so I guess itā€™s more difficult for me to get it in a glance. ill give some more time to it later

1 Like

The API currently (including v2) doesnā€™t allow submitting answers, though that would be nice to have eventually. Of course, it would need a different authorization, since the current API is supposed to be read-only, and for good reason.

I glanced at the discussion on the other threadā€¦ GET/PUT/POST is actually sort of a different thing from read-only/writable API, since you could actually successfully use GET to submit answers (if an API endpoint existed for it). In fact, Iā€™m pretty sure WK originally used GET to submit answers, though of course you have to be signed in.

And while Iā€™m on that topic, itā€™s actually possible right now to do WK from command-line without any API changes. Iā€™ve done it for testing purposes while developing some scripts. You basically just need to call the login URL first, and save the session between calls. Then do some PUT commands to submit answers.

1 Like

You are right, you could, although that is very bad practice :slight_smile:

In particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval. These methods ought to be considered ā€œsafeā€. This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is made aware of the fact that a possibly unsafe action is being requested.

from HTTP/1.1: Method Definitions (Yeah, I take this stuff kind of seriously, although I often write APIs for my job, soā€¦)

I agree that it should have a different authorization as well, and I definitely get why one might want a read-only API. I think it would still be a very cool inclusion to have though, it would make writing all kinds of custom clients way easier.

As for current commandline WK, I assume these are just curl calls using the regular URLs from the website (not API)? Sounds a little tedious, but nice to know itā€™s possible for sure.

1 Like

[I agree about POST being preferable and ā€˜correctā€™]

Yeah, just curl, since I was doing some testing. Itā€™s actually not that bad. Mainly, just submit login/pw, and extract the authenticity_token, which is easier than what youā€™d have to do with a proper authorization protocol that uses a 3rd-party key (i.e. something other than login/pw).

I do this in a bash script.

1 Like

Regarding CLI WK wouldnā€™t it be simpler to make a website that only returns text and then use it through cli browsers like Lynx?
I think itā€™ll be a problem for some made up radicals but you could warn users that the website doesnā€™t support them (or radicals overall).

1 Like

That, and the minor issue that lynx doesnā€™t support JavaScript.

1 Like

point made lmao

1 Like