Gyararī API

Gyararī API is a simple REST API for collecting photos. It was built from scratch using Node, Express, and TypeScript.

Gyararī (Romaji) or ギャラリー (Katakana) literally means “Gallery” in Japanese.

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

Gyararī is a React app running on Heroku at https://gyararii.herokuapp.com and its Storybook (component library for Gyararī) is hosted on Netlify at https://gyararii.netlify.com.

App sleeping... as Gyararī (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 Gyararī API runs on Cloudinary’s free plan, at which point Gyararī API is restricted to transferring data at 25 credits per month. For more information, see Cloudinary 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:

• Cloudinary API key - used together with the API secret to communicate with the Cloudinary API and sign requests.
• Cloudinary secret key - used together with the API key to communicate with the Cloudinary API and sign requests.
• Cloudinary cloud name - the name of your Cloudinary account. Used to build the public URL for all your media assets.

Setup

1. Clone Gyararī API from GitHub repository and change the current working directory:

git clone https://github.com/rxseven/gyararii-api.git
cd gyararii-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:

CLOUDINARY_API_KEY=<YOUR_API_KEY>
CLOUDINARY_API_SECRET=<YOUR_API_SECRET>
CLOUDINARY_CLOUD_NAME=<YOUR_CLOUD_NAME>

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: Gyararī API v0.2.0 has not implemented any unit tests yet.

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

• Fetch images
• Upload images
• Delete images

Back to top

Technology Stack

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

Note: Web application Gyararī 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

• Cloudinary - end-to-end image management solution

Software as a Service

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

Back to top

Related Projects

Gyararī

A simple React app for collecting photos.

Back to top

Development Milestones

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

Back to top

Changelog

See releases.

Acknowledgements

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

Credits

Gyararī API was bootstrapped with TypeScript Node Starter - a starter template for TypeScript and Node.

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