Message API Demo

A REST service that allows clients to create and modify messages and request information about the messages.

Architecture + Docs

For details on the architecture please see here.

For Go documentation run:

make docs

---

Setup

The following are required:

• Go 1.16
• Docker Compose + Docker
• Make

To setup the remaining dependencies run:

make deps

---

Building + Running

Building

To build the application run:

make build

Running

To run specify the database to connect to, ex:

HOST=localhost PORT=8000 DATABASE_URL=postgresql://user:password@host messageappdemo

You can run db migrations prior to running the app via:

MIGRATE=1 ... messageappdemo

You can also run the server with TLS:

KEY=key.pem CERT=certificate.pem ... messageappdemo -tls

Full local example:

make build
docker-compose up -d
MIGRATE=1 HOST=localhost PORT=10443 \
KEY=_examples/cert/server.key CERT=_examples/cert/server.cert \
DATABASE_URL=postgresql://postgres:postgres@localhost?sslmode=disable \
./_build/messageappdemo -tls

---

Development

To run the development server run the following:

docker-compose up -d
go run ./cmd/devserver/devserver.go

# or run the following for more options:
go run ./cmd/devserver/devserver.go -h

To tear the dev database down run:

docker-compose down

To run on docker locally use:

make dev.docker
make dev.docker.down

---

Testing

Tests can be run via:

# run all tests
make test

# run all tests with race detector enabled
make test.race

# run all tests with race detector enabled and clear the test cache first.
make test.race.nocache

You can also test individual packages with the standard Go tooling.

go test ./data # run tests for the data package

You can include property based tests by adding the propertyTests build tag and specify the number of cases via NUM_PROP_TESTS, ex:

NUM_PROP_TESTS=20000 go test --tags=propertyTests ./messages

Coverage

You can check coverage via:

make cover

Or view a coverage report via:

make cover.report

---

API Documentation

You can view the API documentation here or for a nicer experience view it in html at ./_docs/api/html/index.html

The API documentation is written in the openapi json specification generated using openapi-generator.

API Overview

# list messages
curl http://localhost:8000/messages
curl http://localhost:8000/messages?fields=id,message&pageSize=20&pageStartIndex=2

# view message
curl http://localhost:8000/messages/5

# create message
curl -X POST http://localhost:8000/messages --data '{"message":"first"}' \
-H 'Content-Type: application/json; charset=UTF-8'

# update message
curl -X PUT http://localhost:8000/messages/1 --data '{"message":"new message"}' \
-H 'Content-Type: application/json; charset=UTF-8'

# delete message
curl -X DELETE http://localhost:8000/messages/1

Update API documentation

To update the API documentation after changing the /_openapi/messages.json file, run the following:

make docs.api.gen

---

Committing code

Before committing code you should run the precommit make command. The command formats code, runs the tests with the race detector enabled, runs linting, and reports on test coverage.

All tests should pass and no linting errors should be present, ex.:

> make precommit
go fmt ./...
go test -race ./...
ok  	github.com/mdev5000/messageappdemo/data	(cached)
?   	github.com/mdev5000/messageappdemo/postgres	[no test files]
go test -cover ./...
ok  	github.com/mdev5000/messageappdemo/data	(cached)	coverage: 80.5% of statements
?   	github.com/mdev5000/messageappdemo/postgres	[no test files]
staticcheck ./...
go vet ./...

Deployment

Deploy via Heroku

Install the heroku cli https://devcenter.heroku.com/articles/heroku-cli

git clone https://github.com/mdev5000/messageappdemo
cd messageappdemo

heroku login

APP=<name of your heroku application>

# Create an application.
heroku create $APP

# Setup heroku as a remote.
heroku git:remote -a $APP

# Create a postgres database for the application.
heroku addons:create heroku-postgresql

# Flag that the application should migrate the database schema before starting.
heroku config:set MIGRATE=1 

# Set the heroku application to use the docker container file.
heroku stack:set container 

# Push and start the application.
git push heroku main

# Create you first message.
curl "https://$APP.herokuapp.com/messages" --data '{"message":"first"}' \
-H 'Content-Type: application/json; charset=UTF-8'

# And then retrieve it.
curl "https://$APP.herokuapp.com/messages"