A sane and simple Go REST API template. Clone me and edit me to fit your usecase.
What is Gosane?
Gosane is a cloneable API template to get you up and running quickly. It has made a lot of decisions for you, but easily allows you to swap out the things you don't like.
||Social (FB / Google) as well as email based JWT authentication.|
||Database support using the amazing https://github.com/ent/ent package.|
||There's an example AWS SES implementation and an easily extendable interface.|
||Simple JSON and environment based configuration via https://github.com/sno6/config.|
||Prometheus handlers for monitoring.|
||Automatic sentry error logging via: https://sentry.io|
||Validation using an extended version of the https://github.com/go-playground/validator package.|
|Build / Test
||Automatically build and test your code with built in Github pipelines.|
||The underlying server framework is Gin, so you benefit from all the goodness you can find over at: https://github.com/gin-gonic/gin|
Browse the codebase in VS Code here: https://github1s.com/sno6/gosane
Gosane is structured as follows:
Each handler (or endpoint) is grouped and encapsulated in its own folder as can be seen here. Firstly, you must define the relative path for the handler group in a file such as this, and then define each endpoint as a separate handler.
Services & Stores
A handler interacts with your business logic through services, which are aptly defined in
/service. These services interact with your database entities (using ent) via stores. The flow of information should look something like the following:
Handler <-> Services <-> Stores
A store should never be used directly in a handler, and a service should never be used in a store.
Anything that isn't considered business logic should live here. Typically you want to structure these as small modules that you could rip out and run isolated from the rest of the project, if you had to. Examples include, email, database, sentry (error management), etc.
Gosane follows a simple dependency injection plan. All dependencies for your API are defined in
api/register.go. The server initialises all dependencies and passes them through to the handlers via the Register method.
That's about it, the rest is up to you.
How to use Gosane
1. Clone the project
git clone [email protected]:sno6/gosane.git
2. Run the damn thing
Note that if the above command errors you may need to give the script executive permissions by running:
chmod +x ./run.sh
You can download the exported Postman collection
Gosane is complaining about a Sentry DSN, what's that?
In order for Sentry to know where to log errors to it needs a URL. To get one, follow these steps:
- Sign up for a free account over at https://sentry.io/welcome
- Select Go as the platform.
- Copy the Dsn value in the sample code to your
But what if I don't want social OAuth?
Just simply rip out everything for social OAuth. Here's where everything will be:
/api/handler/oauthThis whole folder can go.
/api/register.goRemove the reference to the OAuth handler here.
/config/config.goRemove everything to do with OAuth from the config.
/internal/server.goRemove the fb/google configs that are passed to the API as dependencies.
But what if I don't want Sentry?
Similarly, do the following:
/internal/sentryThis whole folder can go.
/config/config.goRemove all Sentry related config params.
/api/register.goRemove the reference to Sentry from the dependencies list here.
/internal/server.goRemove the Sentry dependency and deferred handler from here.
For any other problems feel free to create an issue and ping me @sno6.
Future work (to be completed in the near future)
- ~80-100% testing coverage.
- Add missing auth related endpoints: "forgot password", "re-send verification email".
- Handle database migrations.
- Transaction rollbacks on recovery state.
- Command line tool to generate new project based on feature requirements.
- Add an example handler to show pagination & sorting usage.