API V2 Alpha Documentation


Anyone else remember that time @viet thought V2 would be would be out of beta in 2017? :stuck_out_tongue:

The recent changes have been really good though. :grin:


I do remember X_X


Awesome, this is great


If this field is removed today it’ll break Tsurukame on iOS :frowning:
I’ve submitted an update to Apple, but as usual they’ve rejected it with no real reason. I’m going to keep trying but I’ve no idea when it’ll be accepted.

I’d appreciate it if you could hold off for a while on deploying this change.
And I know this is still an alpha API, but a bit more warning for breaking changes would be very helpful.


We can hold off for a while — let us know how the review process with Apple goes, and we’ll drop the field when an update is out there. :slight_smile:

We’ll also work on more of a heads up for folks — userscripts can respond a bit more quickly than apps that face review processes…


The update was approved yesterday so it should be ok for you to drop the field now! Thanks so much for the extra couple of days!

Apple reviews are so inconsistent - I just resubmitted exactly the same binary and they approved it without any comments. :thinking:


@viet subject_ids param is prone to overflows (on every endpoint that accepts it) and causes error 500 if fed anything outside the int range (less than −32768 or more than 32767).


I can confirm that. Fortunately the largest subject ID is 8813, so a 16-bit ID is probably fine for now. Assignments and reviews, however are in the hundreds of millions. A 32-bit ID is fine for them right now, but I can see it breaking the limit in a few years.


Thanks for bringing this to our attention.

We are going to have to do better error handling on our end to make sure the values passed in subject_ids are within our DB column size limits.

EDIT: Just issued a PR.


A 2 byte column for the subject ID should be fine. I don’t think the app will ever exceed the limitation.

As for assignments and reviews… Assignment IDs are rolling on a 4 byte column. Just checked the the DB and we still have a very long way to go to reach 2_147_483_647.

The reviews are definitely on their way there though… :slight_smile:


The size is not the main point. It’s just the application should not crash when client accidentally misses a comma, issuing ?subject_ids=123456789 instead of ?subject_ids=12345,6789.


The issue stems from the ID value falling outside the supported range of its column on the database. When this happens the framework we use (Rails) is kind enough to raise an error to inform us one or more of the IDs falls outside the acceptable range (which I see in our log notifications the two attempts made). The problem is the app isn’t rescuing this error and handling it appropriately.


After thinking about it I see your point. We could add a filter before the query to remove any out of range IDs.


Thanks for being patient with me while I finally understood the issue.

I’ve issued another PR which proactively addresses any id filter having any invalid values. The payload should still return a 200 code with the objects for the valid id values.

I’ll let you know when the PR has been merged in.


I’m not sure that’s the best way to handle it. In the event a client misses a comma like @atzkey said, then they need to be made aware that their caller is incorrect and needs to be fixed. It might be be better to catch the bad ids, and return a 400 error that says that the offending ID is invalid. If nothing else, it’ll prompt them to look at their request and hopefully see their problem.


I think that error suppression is a way to go in this case. It should definitely be an error 4xx for a direct /resource/:id request, but in case of filtering params not returning [some of] the requested ids is perfectly fine.

As in: “I am interested in /fruits, ?namely=remons,orenjis,merons. Please show me what you have. Ah, I see, no orenjis, じゃあね, no worries.”


{sigh} Good times with massive review processes.

Well, I’m glad it’s through and the update is in there! We’ll push out the code change on Monday (since we learned a long while ago that production pushes on Fridays mean that one test case you didn’t cover is, in fact, super important and breaks the entire site).