About The Project

   

A Spring Boot API that stores 13108 Kanji characters. The records contain each kanji's meanings, possible readings in both kana and romaji, the number of strokes, JLPT level, Jyoyo Grade and newspaper frequency if applicable. It uses PostgreSQL as a database and Keycloak to secure the protected endpoints. The API is deployed on AWS.
Explore the API »
Explore the docs »

Table of Contents

1. Getting Started
   • Local Setup
   • Prerequisites
2. Usage
   • Open Endpoints
   • Protected Endpoints
3. License
4. Acknowledgments

Built With

• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

The API is deployed on AWS!

Local Setup

Prerequisites

• Docker
• Java (min 17)

The Docker Hub image is meant for the application deployment, so it contains escaped secure data.
To set up the API locally you will have to set up the security and rebuild the image.

1. Navigate to the root directory.
2. Create a .env file that will store all the sensitive data (replace the fields marked with * with the corresponding data):

   POSTGRES_USER=*database username*
   POSTGRES_PASS=*database password*
   KEYCLOAK_USER=*keycloak username*
   KEYCLOAK_PASS=*keycloak password*
   PGADMIN_EMAIL=*pgadmin username*
   PGADMIN_PASS=*pgadmin password*

3. In the Dockerfile replace ENV with corresponding data.
4. Package the .jar with maven:

   mvn clean package

5. Build the docker image:

   docker build --build-arg postgres_user=*database username* --build-arg postgres_pass=*database password* -t name:tag . 

6. In the docker-compose.yaml change the image name of muzukanji service to whatever was chosen in the previous step.
7. Run the docker-compose.yaml

   docker compose up

8. If all images in the container are running you'll be able to access the API at the port 5555

   curl http://localhost:5555/api/v1/kanji

9. To access the secure endpoints you need to set up the keycloak realm at http://localhost:5252. You can use the testing file found under src/main/resources/keycloak/muzukanji-realm.json.

(back to top)

Usage

OPEN ENDPOINTS

1. Paginated list of all kanji

   GET /api/v1/kanji

   The returned JSON contains a pagination header containing the metadata and links to other pages. The data segment contains the list of all kanji containing the kanji itself, it's english meanings and a link to its details. It can be filtered with following optional Request Params:

   Param	Type	Constraints
   kanji	string	Must be japanese characters
   meaning	string	No constraints
   kunyomi	string	Must be japanese characters
   kunyomiRomaji	string	Must be roman characters
   onyomi	string	Must be japanese characters
   onyomiRomaji	string	Must be roman characters
   minStrokes	integer	Between 1 and 34
   maxStrokes	integer	Between 1 and 34
   minJlptLevel	string	One of: N1, N2, N3, N4, N5 (can be lowercase)
   maxJlptLevel	string	One of: N1, N2, N3, N4, N5 (can be lowercase)
   minJyoyoGrade	integer	Between 1 and 10
   maxJyoyoGrade	integer	Between 1 and 10
   minUsage	integer	Between 1 and 2051
   maxUsage	integer	Between 1 and 2051

2. Kanji details, accessed by ID

   GET /api/v1/kanji/1

   It will return the output JSON like:

   {
      "id": 1,
      "kanji": "一",
      "meanings": "One, One Radical (no.1)",
      "kunyomi": "ひと-, ひと.つ",
      "kunyomiRomaji": "hito-, hito.tsu",
      "onyomi": "イチ, イツ",
      "onyomiRomaji": "ichi, itsu",
      "strokes": 1,
      "jlptLevel": "N5",
      "jyoyoGradeTaught": 1,
      "mostUsedInNewspapers": 2
   }  

PROTECTED ENDPOINTS

To access the protected endpoints you need a bearer token issued from the Keycloak API. These endpoints are meant to be used to maintain the database and not be accessible to the client user.

1. Create Kanji

   POST /api/v1/kanji

   Body must contain a properly formatted JSON with the Kanji's data. ID assignment is handled by the database. The Kanji field cannot be null.

   {
      "kanji": "一",
      "meanings": "One, One Radical (no.1)",
      "kunyomi": "ひと-, ひと.つ",
      "kunyomiRomaji": "hito-, hito.tsu",
      "onyomi": "イチ, イツ",
      "onyomiRomaji": "ichi, itsu",
      "strokes": 1,
      "jlptLevel": "N5",
      "jyoyoGradeTaught": 1,
      "mostUsedInNewspapers": 2
   }  

2. Update Kanji

   PUT /api/v1/kanji/1

   It updates the kanji under the chosen ID with the data included in the JSON in the request body. The ID must be an integer not smaller than 1. There must exist a kanji under this ID.

   {
      "kanji": "一",
      "meanings": "One, One Radical (no.1)",
      "kunyomi": "ひと-, ひと.つ",
      "kunyomiRomaji": "hito-, hito.tsu",
      "onyomi": "イチ, イツ",
      "onyomiRomaji": "ichi, itsu",
      "strokes": 1,
      "jlptLevel": "N5",
      "jyoyoGradeTaught": 1,
      "mostUsedInNewspapers": 2
   } 

3. Delete Kanji

   DELETE /api/v1/kanji/1

   It removes the Kanji under chosen ID from the database.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Acknowledgments

• Paul O'Leary McCann for cutlet - a python japanese to romaji converter
• David Gouveia for creating a Kanji JSON dataset I used to initalise the database
• Othneil Drew for creating a great readme template

(back to top)