This project aims to be an example of a relational database-backed REST HTTP Web Server with characteristics needed to ensure success in a high-volume environment. This project co-opts the DIY ethos of the Go community and does its best to “use the standard library” whenever possible, bringing in third-party libraries when not doing so would be unduly burdensome (structured logging, Oauth2, etc.).
I struggled a lot with parsing the myriad of different patterns people have for package layouts over the past few years and have tried to coalesce what I’ve learned from others into my own take on a package layout. Below, I hope to communicate how this structure works. If you have any questions, open an issue or send me a note – I’m happy to help! Also, if you disagree or have suggestions, please do the same, I enjoy getting both positive and negative feedback.
RESTful API Walkthrough
The following is an in-depth walkthrough of this project. This is a demo API, so its “business” intent is to support basic CRUD (Create, Read, Update, Delete) operations for a movie database. All paths to files or directories are from the project root.
Minimum Requirements
- Go
- PostgreSQL – Database
- Google OAuth 2.0 – authentication
- Mage – for build and easier script execution
- CUE – config file generation
Getting Started with the RESTful API Template for Go
The following are basic instructions for getting started. For detailed explanations of many of the constructs created as part of these steps, jump to the Project Walkthrough
Step 1 – Get the code
Clone the code:
$ git clone https://github.com/gilcrest/diy-go-api.git Cloning into 'diy-go-api'...
or use the Github CLI (also written in Go!):
$ gh repo clone gilcrest/diy-go-api Cloning into 'diy-go-api'...
Step 2 – Authentication and Authorization
Authentication
All requests with this demo webserver require authentication. I have chosen to use Google’s Oauth2 solution for these APIs. To use this, you need to setup a Client ID and Client Secret and obtain an access token. The instructions here are great.
After Oauth2 setup with Google, I recommend the Google Oauth2 Playground to obtain fresh access tokens for testing.
Once a user has authenticated through this flow, all calls to services require that the Google access token be sent as a Bearer token in the Authorization header.
- If no token is present, an
HTTP 401 (Unauthorized)response will be sent and the response body will be empty. - If a token is properly sent, the Google Oauth2 v2 API is used to validate the token. If the token is invalid, an
HTTP 401 (Unauthorized)response will be sent and the response body will be empty.
Authorization
- If the token is valid, Google will respond with information about the user. The user’s email will be used as their username in addition to determining if the user is authorized for access to a particular endpoint/resource. The authorization is done through an internal database role-based access control model. If the user is not authorized to use the API, an
HTTP 403 (Forbidden)response will be sent and the response body will be empty.
Step 3 – Prepare Environment (2 options)
All Mage programs in this project which take an environment (env) parameter (e.g., func DBUp(env string)), must have certain environment variables set. These environment variables can be set independently option 1 or based on a configuration file option 2. Depending on which environment method you choose, the values to pass to the env parameter when running Mage programs in this project are as follows:
