API-tools

Warning

This project is still under development!

This is a repository that implement several API interfaces for Discord BOT and web interface.

Currently we have 2 implemented APIs

1. Mark Accent API
2. Mark Furigana API
3. Usage query API
4. Disctionary query API
5. Sentence Query API

Note

The following document is only for developer, we will use Swagger UI to generate official API document.

1. Mark Accent

   Mark accent of given Japanese text

   • Request URL

     https://{TODO}/api/MarkAccent/

   • Request Parameter (POST)

     Note that we only accept POST request

     Parameter	Type	Explanation
     text (required)	string	The text to query

     Sample request

     {
         "text": "お金を稼ぐ"
     }

   • Respond Parameter

     Parameter	Type	Explanation
     status	int	status code Reference
     result	object	An array contains marked results
     surface	string	The original input (partial) text
     accent	list	The accent of given word, with furigana and accent type info. 0 for no accent, 1 for plain, 2 for fall down
     subword	object	An array contains more details when a word contains both kanji and kana
     error	object	An object that describe the details of an error when occur
     error/code	integer	Reference
     error/message	string	Reference

     Sample response

     {
         "status": 200,
         "result": [
             {
                 "furigana": "おかね",
                 "surface": "お金",
                 "accent": [
                     {
                         "furigana": "お",
                         "accent_marking_type": 0
                     },
                     {
                         "furigana": "か",
                         "accent_marking_type": 1
                     },
                     {
                         "furigana": "ね",
                         "accent_marking_type": 1
                     }
                 ],
                 "subword": [
                     {
                         "furigana": "お",
                         "surface": "お"
                     },
                     {
                         "furigana": "かね",
                         "surface": "金"
                     }
                 ]
             },
             {
                 "furigana": "を",
                 "surface": "を",
                 "accent": [
                     {
                         "furigana": "を",
                         "accent_marking_type": 1
                     }
                 ]
             },
             {
                 "furigana": "かせぐ",
                 "surface": "稼ぐ",
                 "accent": [
                     {
                         "furigana": "か",
                         "accent_marking_type": 1
                     },
                     {
                         "furigana": "せ",
                         "accent_marking_type": 2
                     },
                     {
                         "furigana": "ぐ",
                         "accent_marking_type": 0
                     }
                 ],
                 "subword": [
                     {
                         "furigana": "かせ",
                         "surface": "稼"
                     },
                     {
                         "furigana": "ぐ",
                         "surface": "ぐ"
                     }
                 ]
             }
         ],
         "error": null
     }

2. Mark Furigana

   Mark furigana of given text

   • Request URL

     https://{TODO}/api/MarkFurigana/

   • Request Parameter (POST)

     Note that we only accept POST request

     Parameter	Type	Explanation
     text (required)	string	The text to query

     Sample request

     {
         "text": "漢字かな交じり文"
     }

   • Respond Parameter

     Parameter	Type	Explanation
     status	int	status code Reference
     result	object	An array contains marked results
     surface	string	The original input (partial) text
     furigana	string	The marked furigana
     subword	object	An array contains more details when a word contains both kanji and kana
     error	object	An object that describe the details of an error when occur
     error/code	integer	Reference
     error/message	string	Reference

     Sample response

     {
         "status": "200",
         "result": [
             {
                 "furigana": "かんじ",
                 "surface": "漢字"
             },
             {
                 "furigana": "かなまじり",
                 "subword": [
                 {
                     "furigana": "かな",
                     "surface": "かな"
                 },
                 {
                     "furigana": "ま",
                     "surface": "交"
                 },
                 {
                     "furigana": "じり",
                     "surface": "じり"
                 }
                 ],
                 "surface": "かな交じり"
             },
             {
                 "furigana": "ぶん",
                 "surface": "文"
             }
         ]
     }

Build Environment

Download uv and run this command:

uv sync

After build the environment, you should also obtain a Yahoo API Client ID from Yahoo Japan website.

For local standalone development, copy .env.example to .env in this directory and fill in the values:

YAHOO_API_KEY=<Our Yahoo API Key>   # required — app asserts on startup
API_TOOLS_PORT=8000                 # optional — host-side port for docker compose (default 8000)

Authentication (X-API-KEY), CORS, and trusted-host middleware were intentionally removed; this service is expected to run behind the parent backend or on a private network.

In jpcorrect-backend, the equivalent workflow is make api-tools.

How to run?

Run the service with uv (dev mode, with auto-reload):

uv run uvicorn main:app --host 127.0.0.1 --port 8000 --reload

Or run it through Docker from this subdirectory:

docker compose up -d --build

To check the functionality, you may send POST request with curl as follows.

curl -X POST -H "Content-Type: application/json" -d "{\"text\": \"test\"}" 127.0.0.1:8000/api/MarkFurigana/

How to use a shared httpx.AsyncClient?

If your router needs to send HTTP requests, you can follow the instructions below to use a shared httpx.AsyncClientto enhance performance.

import httpx
from fastapi import APIRouter, Depends
from api.dependencies import get_http_client

router = APIRouter()

@router.post(
    "/Foo/", tags=["Foo"], response_model=FooResponse
)
async def foo(
    request: FooRequest, client: httpx.AsyncClient = Depends(get_http_client)
):
    try:
        response = await client.post(url)
    except httpx.TimeoutException:
        ...
    except httpx.HTTPError as e:
        ...