Base API Example

This API example is a basic framework for a REST API

Compiling

This is designed as a go module aware program and thus requires go 1.11 or better You can clone it anywhere, just run make inside the cloned directory to build

Requirements

This does require a postgres database to be setup and reachable. It will attempt to create and migrate the database upon starting.

Configuration

The configuration is designed to be specified with environment variables in all caps with underscores instead of periods.

Example:
LOGGER_LEVEL=debug

Options:

| Setting | Description | Default | | ------------------------------- | ----------------------------------------------------------- | ----------------------- | | logger.level | The default logging level | "info" | | logger.encoding | Logging format (console, json or stackdriver) | "console" | | logger.color | Enable color in console mode | true | | logger.dev_mode | Dump additional information as part of log messages | true | | logger.disable_caller | Hide the caller source file and line number | false | | logger.disable_stacktrace | Hide a stacktrace on debug logs | true | | --- | --- | --- | | metrics.enabled | Enable metrics server | true | | metrics.host | Host/IP to listen on for metrics server | "" | | metrics.port | Port to listen on for metrics server | 6060 | | profiler.enabled | Enable go profiler on metrics server under /debug/pprof/ | true | | pidfile | If set, creates a pidfile at the given path | "" | | --- | --- | --- | | server.host | The host address to listen on (blank=all addresses) | "" | | server.port | The port number to listen on | 8900 | | server.tls | Enable https/tls | false | | server.devcert | Generate a development cert | false | | server.certfile | The HTTPS/TLS server certificate | "server.crt" | | server.keyfile | The HTTPS/TLS server key file | "server.key" | | server.log.enabled | Log server requests | true | | server.log.level | Log level for server requests | "info | | server.log.request_body | Log the request body | false | | server.log.response_body | Log the response body | false | | server.log.ignore_paths | The endpoint prefixes to not log | []string{"/version"} | | server.cors.enabled | Enable CORS middleware | false | | server.cors.allowed_origins | CORS Allowed origins | []string{""} | | server.cors.allowed_methods | CORS Allowed methods | []string{...everything} | | server.cors.allowed_headers | CORS Allowed headers | []string{""} | | server.cors.allowed_credentials | CORS Allowed credentials | false | | server.cors.max_age | CORS Max Age | 300 | | server.metrics.enabled | Enable metrics on server endpoints | true | | server.metrics.ignore_paths | The endpoint prefixes to not capture metrics on | []string{"/version"} | | --- | --- | --- | | database.username | The database username | "postgres" | | database.password | The database password | "password" | | database.host | Thos hostname for the database | "postgres" | | database.port | The port for the database | 5432 | | database.database | The database | "gorestapi" | | database.auto_create | Automatically create database | true | | database.search_path | Set the search path | "" | | database.sslmode | The postgres sslmode to use | "disable" | | database.sslcert | The postgres sslcert file | "" | | database.sslkey | The postgres sslkey file | "" | | database.sslrootcert | The postgres sslrootcert file | "" | | database.retries | How many times to try to reconnect to the database on start | 7 | | database.sleep_between_retries | How long to sleep between retries | "7s" | | database.max_connections | How many pooled connections to have | 40 | | database.loq_queries | Log queries (must set logging.level=debug) | false | | database.wipe_confirm | Wipe the database during start | false |

Data Storage

Data is stored in a postgres database by default.

Query Logic

Find requests GET /api/things and GET /api/widgets uses a url query parser to allow very complex logic including AND, OR and precedence operators. For the documentation on how to use this format see https://github.com/snowzach/queryp

Swagger Documentation

When you run the API it has built in Swagger documentation available at /api/api-docs/ (trailing slash required) The documentation is automatically generated.

TLS/HTTPS

You can enable https by setting the config option server.tls = true and pointing it to your keyfile and certfile. To create a self-signed cert: openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 -keyout server.key -out server.crt It also has the option to automatically generate a development cert every time it runs using the server.devcert option.

Relocation

If you want to start with this as boilerplate for your project, you can clone this repo and use the make relocate option to rename the package. make relocate TARGET=github.com/myname/mycoolproject