掲示板 Forums - Interested in working with a renshuu API?
Top > renshuu.org > Developer corner
Page: 3 of 8
Getting the posts
Page: 3 of 8
Top > renshuu.org > Developer corner
Please try again using the original command - I bet it works alright now.
edict_ent added
a number of config tags added - I'll get a def list out later
usage notes are hidden for now, will decide later if/when to display them.
Please try again using the original command - I bet it works alright now.
It does.
edict_ent added
a number of config tags added - I'll get a def list out later
usage notes are hidden for now, will decide later if/when to display them.
Awesome.
What do you mean by config tags though?
unique-furigana, common-hiragana are a few. Some others from jmdict (a subset).
I just noticed something strange with the add word endpoint.
I have a list and have that list added to two of my schedules.
if I add a word to the list via the Renshuu web dictionary. Reload the page and then look at the the word is included. It shows checkmarks die both the list and the schedules.
if I add the word to the same list via the API instead and then check it via the dictionary, it only shows a checkmark for the list, not for the schedules.
Do you mind trying now? If it still doesn't work, please pass me the curl command so I can drop your key in and replicate it on my end.
Removing the last term from a list using the api causes some issues. I've got a private list called "empty list" that I put a single term in, then removed it with the api. I can no longer see it in api requests, nor in the dictionary "plus button". However, I can see it in my list of lists, and trying to edit it causes an error to show up.
It seems that the dictionary will warn you if you try to remove the last term from a list, asking for confirmation that you want to delete the list.
Oh, nice edge case. What would *you* expect in this case - should it just do it without confirmation?
Actually, I made a mistake. It turns out that the list does show up in the api requests. I think it showed up in a different order so it didn't show up in the same place and I thought it was missing.
As for how to solve the issue, maybe just support empty lists from the community list page. It seems that only the pencil button throws an error here:
Everything else seems to work fine (viewing contents, study button, add to schedule, and delete).
So as long as there is at least one possible argument not in the url, post? I suppose it would make sense then to keep everything post, since there's always the chance that an expansion of the endpoint could result in additional options/settings.
I'm infrastructure engineer, so keep that in mind, I might not give "correct" suggestions, but from my experience one way to approach this would be to have everything POST and in body you have method and all the params. Iirc, that is JSON-RPC protocol, for example:
\"body\": {
\"method\": \"word.get\",
\"word\": \"入る\"
}
OR
\"body\": {
\"method\": \"commynity_list.update\",
\"community_list_id\": \"13482\",
\"word\": \"入る\",
\"force\": \"false\"
}
This looks informative enough from protocol and human understanding perspective. Json is incredibly well readable by human and systems as well
I was absent for some time, will give it a try tomorrow :)
P.S. I strongly recommend having self-descriptive parameters/keys as it eases usage and handling of API for engineers
P.P.S
Oh, nice edge case. What would *you* expect in this case - should it just do it without confirmation?
と言いました。
To handle this I suggest force parameter (like I have in code snippet above). Without force nothing is deleted. Common practice as well
When using the put/delete, the word object should now have either a "result" or "error" field describing what happened.
And, I think you already noted this, but it doesn't need the force (and doesn't delete the lists either - that code was in there, but it's been taken out.)
IMO it's not great design to rely on POST everything; it really defeats the purpose of a RESTful API by doing that. What you're ultimately doing is a GraphQL-at-home by doing that, but more awkward.
I'd start by asking what do you want to let people achieve with the API, then work backwards from there to define the specific actions that requires. IE, "I want people to be able to make community lists via the API" -> POST for creation, PUT/PATCH for updating, DELETE to remove, GET for getting immutable state of it. Overloading the body of a POST means people need to come to your docs and see how you've specifically written it, and bespoke APIs aren't good APIs imho.
There's also OpenAPI (https://github.com/OAI/OpenAPI...) which lets you define your entire API in JSON or YAML which can help with laying it all out/let's you leverage auto doc generation tools, also makes it easier for others to integrate with your API. That's not a requirement, but could be useful to see how others have laid out their APIs (I've linked one example, but there are many out there following the 3.x spec).
You're likely going to go back and forwards on how you want it to look like, which is critically why you should ensure the version is part of the path; if you find you need to change the API schema, rather than initially have it all be POST to give you wiggle room, it's better practice to just bump from /v1/words -> /v2/words. Here v2's words endpoint has breaking changes that mean a client can't use it the same way they could use v1. "Use" here means the data that comes back is at least the same, you could keep enriching the responses and not bump the API version (IE you add in the furigana to the response, that's not a breaking change to your consumers, as the old fields are still there as they were), but changing the format of the response (maybe you return an array of words now instead of a string), would warrant a bump to v2 (basically the contract you gave them with v1 no longer is true)
While I continue to work on the term interface, I'd like to jump into schedules next. Repasting what was mentioned earlier:
GET /v1/schedules { "user": "abc", "schedules": [ { "name": "Genki 1 Words", "review": 123, "learn": 123 }, ... ] }
Here's everything I can think of that you may need for any schedule
name
id
term stats (# of terms, hidden, studied, not yet studied, cannot study)
review/learn for the day
# learned for today, this week
current pace settings
Anything else?
Not that I can think of. The Kanji helper schedule stuff is still in development, but once that's more solidified maybe including that schedules id could be handy (if one exists)?
That schedule endpoint has me
Don't have all the info, but the basics are in there
GET /v1/schedule
GET /v1/schedule/:id
enjoy!
👋 おはよう!
Could I get an API key & an OpenAPI spec too (if there is one)? 😄
(a YAML that can be imported into https://editor.swagger.io/ for instance )
I'd love to work on a HomeAssistant plugin that queries Renshuu for the user's level and keeps track of it, allowing reminder automations or just general dashboarding things.
👋 おはよう!
Could I get an API key & an OpenAPI spec too (if there is one)? 😄
(a YAML that can be imported into https://editor.swagger.io/ for instance )
I'd love to work on a HomeAssistant plugin that queries Renshuu for the user's level and keeps track of it, allowing reminder automations or just general dashboarding things.
You can get your API key if you go to the experimental section of the settings.
Nothing yet in terms of specs, those will come later when I feel comfortable enough that the data coming in/out is relatively stable in terms of names, etc.
Hi everyone,
I've written a chrome extension that uses the new renshuu apis. It is open sourced here: https://github.com/buruburukun/renshuu_helper You can use it to search for terms on any website and add them into lists and schedules. Please give it a try. It is not published to the chrome web store yet as things are still unstable. There are installation instructions in the readme. If you have any issues or suggestions please let me know.
The following is for Michael.
Questions:
1. What is the meaning of this in search results?
"config": { "3": "ent_primary" }
What are all the possible values? For example, I've also seen
"1": "unique-furigana"
Bugs:
1. Inconsistent dictionary results?
Searching for 入賞 using the api (note that there are 2 definitions in the list):
"def": [ "winning a prize, placing (high", "in a contest)" ]
Searching on renshuu (note the semicolon):
winning a prize, placing (high; in a contest)
2. You can attempt to PUT/DELETE a word from a schedule that does not exist (perhaps it is someone else's schedule?), and the request succeeds (200) with no result/error field. I hope this wouldn't edit someone else's schedule.
3. For GET /v1/word/:id requests, the returned total_pg always seems to be 0. I did some calculations to determine the maximum page.
4. For GET /v1/word/:id requests, if the requested page is greater beyond the last page, the returned page will be the last page, and the returned "pg" will be 0. Similarly, if the requested page is negative, the first page will be returned and "pg" will also be 0.
Feature requests:
1. Can we get the word ids for the alternate forms? I believe these can be added into lists/schedules, but searches only have the id of the main entries.
2. Can we streamline getting the api key into the extension? I've got right click on renshuu -> populate the api key in the extension, but it involves opening the settings panel to get the appropriate element loaded (and some imprecise selectors). I think the easiest would be a hidden element that is always present that can be referred to by id. Or if someone else has good suggestions for how to do this...