README.md

Golang RESTful API Example Project

Project contains some simple Golang application, implemented RESTful service for some abstract financial company.

• Golang RESTful API Example Project
  • Requirements
    • Golang
    • Docker
    • Database
  • Development
  • Quick Start
    • In Docker
    • Manual
  • Contributing
  • Additional Documentation
  • Contacts

Requirements

Golang

Project was tested on Go 1.13.3 and 1.13.4, but theoretically should compile on 1.11/1.12 too (all versions with modules support).

Docker

Docker is not directly required to run application. But for quick start you can use it. So this way you should have docker and docker-compose installed on the machine.

Database

Project was tested on PostgreSQL 12.0, but theoretically should works fine with old versions too. You can use docker to run test database instance or you can use your own database installation.

Development

To develop this project, you should clone it:

git clone https://github.com/Toshik1978/go-rest-api.git

Then you can open it in your preferred editor and have a fun. Project provides Makefile to lint/test/build application. Default make command run linter over the project's code, unit tests and finally build binary. You can manually run linter or linter with tests with the following commands:

make lint
make test

Pay attention, that test rule always run lint rule.

If you want to skip all stages, except build you can build-only project:

make build

Quick Start

In Docker

.scripts folder contains some useful shell scripts to quick look into the project. Default Dockerfile and docker-compose.yml provides the fastest way to run application.

To instantiate default database instance, run all migrations and start application, you can do:

.scripts/run.sh

Docker allows to run multiple instances of the project. You can add to docker-compose.yml additional containers like restapi and map different port to 8080 port inside of container.

Manual

You can start working with project manually.

First of all you should install dependencies to run migrations:

make prereq

Then install yq (command-line YAML processor). Please, refer documentation for installation details.

With prerequisites installed you can instantiate database. Run:

.scripts/run.services.sh

Then you should run migrations to create database scheme.

.scripts/migrate.sh

Of course you can install database other preferred for you way. This way you should manually create empty database and update application's configuration file to your actual connection string.

Finally you should build project and run it.

make
./go-rest-api

Project contains kind of production configuration file for Docker and docker-compose-production.yml. You can use it instead of previous step with manual build outside of Docker. This way you should build image:

make docker

And then run docker-compose with production configuration file.

Contributing

If you want to contribute into project, you can fork it, change it and create MR. I'll surely look at this!

Additional Documentation

You can find more information about project in the following documents:

1. Architecture
2. API description

Contacts

You can address any questions on e-mail in public profile.