API V2 Beta Documentation

Well, getting a response for only one array member at a time is kind of a painā€¦

Iā€™m not super familiar with Kotlin or Retrofit, but it looks like thereā€™s some discussion of getting a URL encoded string for an array over at the Retrofit repo on Github. Itā€™s a little dated, but the current documentation for @Query provides some details. I think youā€™ll need to use the encoded=true option, though thatā€™ll require some testing. Hopefully this helps (rather than just restating something youā€™ve already explored).

Like I said, Viet and I will discuss this one soon ā€” weā€™ll have a clear answer with rationale on the topic by the time we take this to beta.

1 Like

Iā€¦ I totally missed that. Guess I was too fixated on thinking it wasnā€™t supported out-of-the-box. Iā€™m sorry. The solution provided there works perfectly (though I still think comma separation is better! :stuck_out_tongue:).

This is delving into the auth topic again, but Iā€™m curious why the API key is required for cases where the user already has a valid login session established. Would it be possible to accept both forms of auth for the API? It would certainly make life easier for user scripts and the like. This made all the more compelling to my mind seeing as the API is read-only as I understand it, with nothing more sensitive than progress statistics. Did I get this right?

For folks writing iOS apps then all they would need to do is code to the initial login form post that you have any then continue on by maintaining all set cookies in subsequent requests.

From an app perspective, Iā€™m not opposed to using an API key separate from the session cookie. Using the session cookie as a token means I have to be concerned with the expiration of the cookie, and subsequent resubmission of login credentials (which would need to be securely stored) to create the new one (which currently involves submitting a web form with an embedded ā€œauthenticity tokenā€).

What I would prefer is a JSON endpoint that I could query with a valid session cookie to retrieve the API keys, which would create them if they donā€™t exist. Saves having to rely on JavaScript to read input fields from the settings page, and submit the web form if the API key hasnā€™t yet been generated.

2 Likes

Alright, the change is made and up on the site. No more 404s for empty result sets, just ā€¦ empty result sets. Invalid values for keys, or pagination values outside the min/max will still give you 422s, though. The documentation has been updated ā€” let us know if youā€™ve got any questions.

3 Likes

This change seems to have worked well for my userscript! (This means all the SRS levels will be shown by my script, regardless of whether or not the user has any items in them. This is a negligible change, but not a negative one.)

Good change. :slight_smile:

How has working with the new API been for you?

Iā€™m going to start working with APIv2 today.
No problems with the few tests Iā€™ve run previously, though.

Oh, you beat me to it!

1 Like

Iā€™m pretty sure this isnā€™t, for example, a W3C standard. Iā€™ve never seen this in a REST API. It may be used in some frameworks, but itā€™s certainly not universal or standard.

Right, wasnā€™t suggesting it was a universal standard. AFAIK, there isnā€™t a universal standard on URI encoding for lists. As mentioned before it is set up to use the standards set by the framework we are using. And changing it to something else is something we are now discussing.

Whatever you do decide, you should specifically document it, since reading this I didnā€™t know how you wanted array parameters serialized. Others bring up a good point that this makes for seriously unwieldy URLs if your array is more than a few items long.

1 Like

We will document this better when it gets closer to out of beta.

Overall I had a good time making my userscript with the API, but itā€™s a fairly simple one. The process was also probably tainted by the fact that I didnā€™t code anything for at least five or so years, and the fact that I had to code in javascript.

My list of things that confused me:
1: ā€œtoken tokenā€ - I donā€™t know why you did it this way, Iā€™m sure thereā€™s a reason, but this needs to be documented well, itā€™s confusing.
2: The way you pass arrays is weird. =. Iā€™m not sure if this is actually the API or just the internet being weird and wonderful as always. Itā€™s not that bad if you introduce it in your documentation though.
3: Iā€™m pretty sure Iā€™m not doing the caching correctly. This is more my fault than yours probably, but if you want hobbyists like me to use it, it needs to be well documented.

4: Javascript promises. Again, not your fault but holy **** I spent the better part of a day trying to understand that. Iā€™m probably a better person for having learnt though.

1 Like

Were you able to get anywhere with your SSL optimizations? SSL Sessions (of either flavour) will probably help a lot with JS clients, but not so much with other languages as client-side session resumption usually requires extra effort from the developer.

Lolā€¦
I feel like Promises are a 20th century solution to a 21st century problem. Theyā€™re not a natural way of thinkingā€¦ or, at least, not as implemented. We need better languages. Frankly, we need to grow beyond text-file languages. Asynchronous and parallel coding are so much easier when youā€™re not confined to linear source code documents.

We hit a roadblock, unfortunately.

The app is on Heroku, which limits to how much access we get on customizing the webserver. We did ping them and they didnā€™t offer much of a solution. It seems if this is going to be addressed we need to figure it out at the app level :confused: Read some things about setting SSL handshake to Keep-Alive, but havenā€™t made it passed that.

Iā€™ve rewritten AlliCrab to use API v2, and Iā€™ve got an alpha version Iā€™ve been using for a couple days. The new API is definitely a massive improvement over the old and overall Iā€™m fairly happy.

The only thing I wasnā€™t sure about is how we know a resource has been deleted when using the updated_after filter. Particularly deletion of assignments/review_statistics/study_materials when someone resets their level.

Hrm, solid point about the deleted records. Viet and I will put our head together and see how we can accurately report on that through those endpoints. Just like the directions say, we destroy the records when a user resets, so we donā€™t have anything left to report onā€¦ :thinking:

That sounds like something to leave up to clients (i.e. devs using the API). The client can check current user level, then manually delete cached data if they so choose, or retain the data if that makes sense to their use case. I donā€™t see any reason for the server to deal with it.