RESTful recipes

A more formal REST API in Golang.

This builds on my Simple REST API in Golang.

All data is stored in PostgreSQL, all transfer is via JSON.

All dependencies are handled via Docker and docker-compose.

TDD (Test-Driven Development) is implemented; the build will fail if the tests do not pass.

Likewise the build will fail if either golint or go vet fails.

Enforces industry-standard gofmt code formatting.

All testing can be done with curl.

Features

• uses httprouter
• uses Pure Go postgres driver
• uses sqlx
• uses testify assertions

sqlx

sqlx offers some database/sql extensions.

There is a useful Illustrated guide to SQLX.

It is not exactly a drop-in replacement for database/sql, as it is not quite a full superset. I found that I still needed to import both dependencies due to some primitives (such as ErrNoRows) that are not included in sqlx.

I am not entirely sure I would use this library in my normal workflow, although it does offer some interesting new options (the Illustrated Guide is very helpful here).

testify assertions

In terms of simplifying tests, testify assertions really make test cases much clearer - while also cutting down on boiler-plate.

I'm generally pretty reluctant to introduce additional external dependencies unless they really deliver value. In my opinion this addition is justified as the test cases become much easier to follow with assertions.

To Run

The command to run:

$ docker-compose up -d

For the first run, there will be a warning as mramshaw4docs/golang-alpine:1.8 must be built.

This image will contain all of the Go dependencies and should only need to be built once.

For the very first run, golang may fail as it takes postgres some time to ramp up.

A successful golang startup should show the following as the last line of docker-compose logs golang

golang_1    | 2018/02/24 18:38:01 Now serving recipes ...

If this line does not appear, repeat the docker-compose up -d command (there is no penalty for this).

To Build:

The command to run:

$ docker-compose up -d

Once make indicates that restful_recipes has been built, can change docker-compose.yml as follows:

1. Comment command: make

2. Uncomment command: ./restful_recipes

For testing:

[Optional] Start postgres:

$ docker-compose up -d postgres

Start golang [if postgres is not running, this step will start it]:

$ docker-compose run --publish 80:8080 golang make

Successful startup will be indicated as follows:

2018/02/24 16:27:10 Now serving recipes ...

This should make the web service available at:

http://localhost/v1/recipes

Once the service is running, it is possible to curl it. Check CURLs.txt for examples.

See what's running:

The command to run:

$ docker ps

View the build and/or execution logs

The command to run:

$ docker-compose logs golang

To Shutdown:

The command to run:

$ docker-compose down

Clean Up

The command to run:

$ docker-compose run golang make clean

To Do

• Upgrade to latest Go (as of posting, 1.15.4)
• Add Basic Auth to certain endpoints (POST, PUT/PATCH, DELETE)
• 12-Factor Basic Auth parameters
• Fix code coverage testing
• Upgrade to latest Postgres
• Persist back-end Postgres
• Add a SWAGGER definition
• Refactor data access into a DAO module
• Add tests for the DAO
• Add a health check
• Migrate from Gorilla/mux to julienschmidt/httprouter
• Migrate to sqlx for some sql extensions
• Implement testify assertions
• Implement testify suite
• Implement CORS
• Implement graceful shutdown (available since Go 1.8)
• Add Prometheus-style instrumentation

Credits

Inspired by this excellent tutorial by Kulshekhar Kabra:

https://semaphoreci.com/community/tutorials/building-and-testing-a-rest-api-in-go-with-gorilla-mux-and-postgresql