A basic but fully functional API has been added in ssmtool
version 0.3. The
goal of this is to enable extensions for other programs, such as ebook readers
or video players, to depend on ssmtool’s infrastructure and configuration.
For developers, this can greatly reduce the workload since there is no longer a need to program dictionary processing or lemmatization functions. For users, they will only need to configure one tool rather than 3. Moreover, features that would otherwise be absent for many simpler plugins such as lemmatization will be available.
The current API only provides the features already in ssmtool, but in the future the plan is to add features such as images and audio primarily in the API, since ssmtool is mainly a text-oriented tool.
Here is a table for the current API endpoints for reference.
Verb | Path | Usage |
---|---|---|
GET | /healthcheck |
Check if API is online |
GET | /version |
Get the version of API running. The current version is 1, which is the only possible value now. |
GET | /define/<word> |
Get the definition of a word. The response is a definition item. Lemmatization depends on user setting. |
GET | /define/<word>?lemmatize=false |
Get the definition of a word regardless of user settings without lemmatization. |
GET | /lemmatize |
Get the lemmatized form of a word. Response is a simple string. |
GET | /logs |
Get the full database containing all past lookups and note creations |
GET | /stats |
Get data about lookups and new cards today |
POST | /createNote |
The request body should be a note item. |
Data formats
Definition item
Depending on whether the user has a second dictionary source enabled, it can be either:
{
"word": "blue",
"definition": "a color..."
}
or
{
"word": "blue",
"definition": "a color...",
"definition2": "azĂșl"
}
Note item
{
"sentence": "The quick brown fox jumps over the lazy dog.",
"word": "fox",
"definition": "an animal..",
"tags": []
}
Please note that even with “tags” being an empty array, the default tags specified in ssmtool config will still be added.
Using two definitions is not yet supported. It should be added soon, along with an interface to determine user settings since not all users will have a second definition field set.
Image and audio data fields will also be added in the future.
API users
Currently the author of mpv immersive script has plans to support the API, at least as a dictionary function, which will transparently provide lemmatization and handling of accents and other textual features in different languages.