Tsūka API

Tsūka API is an extremely simple REST API for converting currencies. It was built from scratch using Node, Express, and TypeScript.

Tsūka (Romaji) or 通貨 (Kanji) literally means “Currency” in Japanese and 通貨換算ツール (tsūka kansan tsūru) means “Currency Convertion Tool” or “Currency Converter”.

Table of Contents

Getting Started

• Live Demo
• Configuring the Development Environment

Specifications

• Features
• Technology Stack
• Development Workflow
• Third-party Services
• Related Projects

Appendix

• Development Milestones
• Changelog
• Acknowledgements
• Credits
• Licenses

Live Demo

Tsūka is a React app running on Heroku at https://tsuuka.herokuapp.com and its Storybook (component library for Tsūka) is hosted on Netlify at https://tsuuka.netlify.com.

App sleeping... as Tsūka (React app) and its API (this repository) run on Heroku’s free plan, when an app on Heroku has only one web dyno and that dyno doesn’t receive any traffic in 1 hour, the dyno goes to sleep. When someone accesses the app, the dyno manager will automatically wake up the web dyno to run the web process type. This causes a short delay for this first request, but subsequent requests will perform normally. For more information, see App Sleeping on Heroku.

Monthly limit as Tsūka API gets current and historical foreign exchange (Forex) rates from Fixer’s free plan, therefore Tsūka API is restricted to making 1,000 API calls per month. For more information, see Fixer Plans.

Back to top

Configuring the Development Environment

Prerequisites

Tools

Before getting started, you are required to have or install the following tools on your machine:

• Git (v2.17.2*)
• GNU Bash (v3.2.57*)
• nvm (v0.33.5*) and Node.js (v10.15.1*)
• npm (v6.4.1*) or Yarn (v1.3.2*)

Optional, but nice to have:

• Visual Studio Code**
• Postman**

Note: if you are using Mac running macOS (v10.12 Sierra*), you are set with Git and GNU Bash.

Note: this project has been pre-configured for use with Visual Studio Code.

Software as a Service

You also need to have to the following information beforehand:

• Fixer API key - a unique key assigned to each API account used to authenticate with the API.

Setup

1. Clone Tsūka API from GitHub repository and change the current working directory:

git clone https://github.com/rxseven/tsuuka-api.git
cd tsuuka-api

2. Open the project with your editor of choice or with Visual Studio Code.

3. Switch to a specified Node version:

nvm use

4. Create .env file and add the configuration below:

FIXER_API_KEY=<YOUR_API_KEY>

Note: environment variables files are listed in .gitignore file to ensure that they will not be tracked by the source control.

Starting the development server

1. Start the development server by running the command below:

yarn start:watch

This command will first compile (build) source code written in TypeScript in ./src directory to plain ES5 JavaScript using TypeScript compiler. Once the app was built to ./build directory, Nodemon will then start the Express server and listen for incoming connections on port 5000.

Note: this command will monitor for any changes and automatically re-compile source files and restart the server.

2. Open http://localhost:5000/api/v1/gallery in Postman or any HTTP client of choice.

Tip: press control + c to stop the development server.

Running tests

Run one of the following commands to run tests with Jest and SuperTest:

yarn test
yarn test:coverage
yarn test:watch
yarn test:watch:silent
yarn test:watch:verbose

Note: by default, when you run test in watch mode, Jest will only run the tests related to files changed (modified) since the last commit. This is an optimization designed to make your tests run fast regardless of how many tests in the project you have. However, you can also press a in the watch mode to force Jest to run all tests.

Note: code coverage reports will be generated in the local ./coverage directory. This directory is listed in .gitignore file to ensure that it will not be tracked by the source control.

Tip: press control + c to stop the running tests.

Running code linting

Run one of the following commands to run code linting with ESLint:

yarn lint
yarn lint:fix

Formatting code

Run the following command to format your code against Prettier and ESLint rules:

yarn format

Creating a production build

Run the command below to build the app for production:

yarn build

Note: the production build will be created in the local ./build directory. This directory is listed in .gitignore file to ensure that it will not be tracked by the source control.

Running the production build locally

1. Run the following commands respectively to create a production build and start the server locally:

yarn build
yarn start

2. Open http://localhost:5000/api/v1/gallery in Postman or any HTTP client of choice.

Tip: press control + c to stop the server.

Back to top

Features

Convert currencies using daily Fixer's Forex rates.

Back to top

Technology Stack

• Node, Express, TypeScript
• CORS, Body-parser, .ENV, Lodash
• More...

Note: Web application Tsūka can be found in this repository.

Back to top

Development Workflow

• JavaScript compiling/transpiling with TypeScript
• TypeScript linting with ESLint
• Code formatting with Prettier
• Automate testing with Jest, SuperTest, and Nock
• Static type checking with TypeScript
• Pre-commit hooking with Husky and Lint-staged
• CI/CD with GitHub, Travis CI, and Heroku

Back to top

Third-party Services

Infrastructure

• Heroku - cloud platform as a service

Cloud computing and Platforms

• Fixer - API for current and historical foreign exchange (Forex) rates
• REST Countries - API for getting information about countries
• Country Flags - API for loading any country flag

Software as a Service

• GitHub - web-based hosting service for version control using Git
• Travis CI - continuous integration

Back to top

Related Projects

Tsūka

An extremely simple React app for converting currencies.

Back to top

Development Milestones

• Add unit tests
• Add request validation
• Optimize the app’s performance
• More...

Back to top

Changelog

See releases.

Acknowledgements

Tsūka API is an open-source project built and maintained by Theerawat Pongsupawat, frontend developer from Chiang Mai, Thailand.

Credits

This project was bootstrapped with Gyararī API.

Licenses

The content of this project itself is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International license, and the underlying source code is licensed under the GNU AGPLv3 license.

---

* the minimum required version or higher | ** the latest version