掲示板 Forums - Interested in working with a renshuu API?

The API is live for testing!

https://api.renshuu.org/docs/

API Key can be found under the experimental panel of renshuu's settings (tap menu, then the settings icon, then search for "api")

Current endpoint

While the endpoints are listed in detail in the above docs, here's a quick overview:

/profile - personal study stats

/schedule - info on your schedules, including ways to list schedule contents

/word, /kanji, /grammar, /reibun - ways to search renshuu's dictionaries/sentence library. Includes actions for adding/removing content to your lists and/or schedules

Planned endpoints

/list - way to view all lists you've made, as well as the contents of the lists

/shiritori - way to start, view, and interact with private shiritori games. Access to public games will not be available

What the API will *not* contain

I am not planning to add any of the quizzing functionality to the API now or in the future.

Planning on building off of the API?

If it's a public tool, please drop a link here and describe it! I plan to have a showcase page if we get enough tools (big or small), and I'll be giving out renshuu pro to most people who make something and share it with the community.

I was going to say something similar. I have .srt subtitle files for movies + shows, and song lyrics that would be great to be able to upload more easily. Not sure I would actually use an API to upload them, but the option would be nice.

The Text analyzer could also just use some attention, since it and the Reading Buddy feel more like unpolished prototypes.

First of all great to see you moving forward with the idea of providing an api.

I guess you already know what I'd want to use it for, but it probably makes sense to mention it here too.

I'm using the yomichan/yomitan popup dictionary browser plugin. I would find it very useful to be able to add words, I look up with it, directly to a renshuu list.

It already has a function to create anki cards from looked up words by calling an API that anki provides.

To make it work with renshuu as a backend instead of anki I think there would be 3 ways to do it
* create a program to run locally to convert api calls from yomichan to the renshuu api format
* offer an api on the renshuu server in the format the yomichan plugin expects, so it can connect directly to it
* add functionality to the browser plugin, so it uses the renshuu api and either fork it or talk to the developers of they would accept to integrate that change.

(There's also the 10ten reader browser plugin which is similar. It currently doesn't have a feature to export looked up words, but the developer seems to be working at this function. But there isn't much information when it will be available and how configurable it will be. https://github.com/birchill/10... )

Simillar to Ikuto, my main interest is to be able to integrate other sources of learning with Renshuu. For me and my friends this usually involves using Yomitan extension to help with reading. Currently, if we want to add words to Renshuu while doing that, it involves a lot of actions that force a significant slow down and disruption, and we can't use Yomitan for assistance with it.

Given the plugin's very wide spread, I think it is very worthwhile to add some support for the extension or at least let us write proper plugins for it.

I was under the impression that Yomitan itself made it somewhat difficult to interface with renshuu - ikuto was able to write some code, but it also required a little server to be running somewhere in between yomitan and renshuu's api.

The middle layer seemed like the path of least resistance to me as I have no experience with writing browser addons and it's probably hard to use an self built addon on a mobile browser.

The data is there, the script just doesn't extract it. What the script receives is formatted exactly like the entries in the popup dictionary (there's an optional line of text "(Rarely written as: ...)" at the end of each entry)

Specifically I'd be interested in:

- GET stats: Access to the stats associated with the current user would be useful. Default to all time. Example:

GET /v1/stats/?window

{
    "user": "abc",
    "total_xp": 123,
    "level": 123,
    "statistics": [
        {
            "type": "grammar",
            "terms": 123,
            "questions": 123,
            "correct": 123,
            "new_terms": 123,
            "window": "today"
        },
        ...
    ],
}

- GET streak: I'm sure this data is recorded somewhere since the 30d streak applies a debuff on the xp gain. Could probably bundle the xp and level in here too, but just an example. Example:

GET /v1/streak
{
    "user": "abc",
    "streak": 123
}

- GET upcoming schedules/schedules due: Simply return a list of the currently subscribed schedules along with the relevant stats. Example:

GET /v1/schedules
{
    "user": "abc",
    "schedules": [
        {
            "name": "Genki 1 Words",
            "review": 123,
            "learn": 123
        },
        ...
    ]
}

- GET challenges: Similar to above, but for the days challenges. Example:

GET /v1/challenges
{
    "user": "abc",
    "time_left": 123, (think time until reset)
    "challenges": [
        {
            "name": "Answer 1 question in the question corner",
            "link": http... (ie this link takes you to the question corner),
            "percentage_complete": 123,
        },
        ...
    ]
}
        

- POST shiritori answer: Pretty self explanatory, needs a corresponding GET to get the id of the game you want to post to, but takes some kind of JSON body to post an answer to a Shiritori round and responds with whether you succeeded or not.

Edit: I see that the full history isn't stored in DB (makes sense), but an additional field on a user that tracks the # of days studied consecutively that updates once a day shouldn't be too onerous on the DB (I hope). At the end of the month can just set the field to be equal to the curr_val + this months streak, if the streak gets broken in Renshuu then that value gets reset. So theoretically could reduce number of DB work by just using the existing 30d window + an int stored on the profile that gets updated at the start of a month with the latest streak of the past month, then every call to the streak endpoint just adds that int with the current months streak?

I'll be getting an official api key thing setup sooner than later, but if you want an api key for testing, let me know.

regarding docs generation. For python there's a library called fastapi where you can just define data classes and functions for the endpoints. It then auto generates documentation from the code.

maybe something similar exists for PHP too.

I have very limited experience in maintaining a web api, but based on what experience I do have, I would lean towards having as few endpoints as possible. So the v/resource/id/action template seems like a good one to me.