Gosane 🧘‍♀️

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.

Features

Structure

Browse the codebase in VS Code here: https://github1s.com/sno6/gosane

Gosane is structured as follows:

Handlers

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.

Internal

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.

Dependencies

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

./run.sh

Note that if the above command errors you may need to give the script executive permissions by running: chmod +x ./run.sh

Postman

You can download the exported Postman collection here.

Potential issues

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:

1. Sign up for a free account over at https://sentry.io/welcome
2. Select Go as the platform.
3. Copy the Dsn value in the sample code to your .env file.

That's it.

But what if I don't want social OAuth?

Just simply rip out everything for social OAuth. Here's where everything will be:

1. /api/handler/oauth This whole folder can go.
2. /api/register.go Remove the reference to the OAuth handler here.
3. /config/config.go Remove everything to do with OAuth from the config.
4. /internal/server.go Remove the fb/google configs that are passed to the API as dependencies.

But what if I don't want Sentry?

Similarly, do the following:

1. /internal/sentry This whole folder can go.
2. /config/config.go Remove all Sentry related config params.
3. /api/register.go Remove the reference to Sentry from the dependencies list here.
4. /internal/server.go Remove 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.