starter

README

Golang REST API starter

This go starter is here for you to take it and modify according to your needs. This project promotes ideomatic go code. And if there's any parts which has a bad design pattern, expects you to provide feedback by opening a issue.

What is this?

The idea is to have everything included (a.k.a. batteries included) starter project, after which all you need to do would be to work on your idea, instead of setting everything up.

Backend

• MongoDB for data storage
• redis for caching
• docker for providing redis and MongoDB for development

What features are included?

This project provides the following features:

• JWT based Authentication
• Pre configured endpoints (see handlers for more info)
• Permissions
• Middlewares (includes must_have_permission, rate_limit, auth_middleware etc)
• Pre defined way of using Database with integration tests
• Ability to cover 100% of code with tests
• Ability to unit test each handlers
• Transformers (so you can transform your db representation into response)
• mocking (using mockgen)
• migrations
• redis cache
• .env config
• commands
• travis and circleci support
• docker-compose for database and redis
• logging with logrus (and slack pre configured)
• easy email support
• sign up
• login with open auth provider
• recaptcha support (spam protection)
• open auth server
• command line tool to generate handlers, middlewares, etc
• limit login attempts
• side effects handling
• And more to come

Packages Used

• dep for managing packages
• gorilla mux for routing
• logrus for logging
• respond.v1 for responding to requests
• mgo for connecting to mongodb
• go-redis for redis
• testify for testing
• captain for monitoring cron jobs
• jwt-go for handling Auth using JWT
• go-slack for logging to slack
• mock for mocking interfaces
• pushy for sending push notifications to devices

Ready to use?

As of v0.0.1, this boilerplate is ready for anyone to adapt, modify and use. But beaware, that it's upto you to make this production ready and usable for your needs.

Upcoming changes

There WILL be breaking changes for a while till this gets to stable, production ready state, till then, you can watch changes closely and adapt to it.

Getting Started

As of now, it's not an application, but a package, it's because app engine requires you to do so. This doesn't depend on app engine, but because of it's popularity, it made sense to declare as a package which can be invoked really easily.

If you don't plan on going that route, you can always modify package name to your needs.

If you'd just like to see this working, follow the following steps:

• make sure you have docker and docker-compose
• make sure you've got go toolchain installed (older versions work, but they tend not to ignore vendor directory, so better to use newer go versions
• Then follow the following commands

cd $GOPATH/
mkdir -p src/github.com/fossapps/starter
cd src/github.com/fossapps/starter
git clone git@github.com:fossapps/golang_starter.git . # or you can use http url if you'd like

• then cd into starter directory
• run cp .env.example .env
• run dep ensure
• run docker-compose up
• run make serve

At this point, you'll have a API server running on port 8080 feel free to experiment.

More Documentation

If you decide to use this for your needs, there are a few things which you might have to keep in mind while using this starter project.

Visit WiKi to know how to move forward.

Contributing

If and when you encounter some pain points or bugs, please feel free to open a new issue

See contributing.md to get started with contributions.

License (MIT)

Visit license to see if this fits your needs.

Documentation

Index

• func Init()
• func NewRouter(s Server) *mux.Router
• type Constants
  • func Const() Constants
• type LoginResponse
• type MetricPermissions
• type NewRegistration
• type NewUser
  • func (user NewUser) Ok() bool
• type NotificationPermissions
• type Permission
• type Permissions
• type RefreshTokenHandlerResponse
• type RegistrationResponse
• type RequestHelper
• type Server
  • func (s Server) CreateUser() http.HandlerFunc
  • func (s *Server) DeleteSession() http.HandlerFunc
  • func (s *Server) ErrorResponse(w http.ResponseWriter, r *http.Request, statusCode int, message string)
  • func (s Server) GetUser() http.HandlerFunc
  • func (s *Server) ListPermissions() http.HandlerFunc
  • func (s Server) ListUsers() http.HandlerFunc
  • func (s *Server) LoginHandler() http.HandlerFunc
  • func (s *Server) RefreshTokenHandler() http.HandlerFunc
  • func (s *Server) RefreshTokensList() http.HandlerFunc
  • func (s *Server) RegisterHandler() http.HandlerFunc
  • func (s *Server) SuccessResponse(w http.ResponseWriter, r *http.Request, statusCode int, message string)
  • func (s Server) UpdateUser() http.HandlerFunc
  • func (s Server) UserAvailability() http.HandlerFunc
• type SimpleResponse
• type UserAvailabilityRequest
• type UserAvailabilityResponse
• type UserPermission

Functions

func Init

func Init()

Init actually starts listening and server on a port

func NewRouter

func NewRouter(s Server) *mux.Router

NewRouter returns a configured router with path and handlers

Types

type Constants

type Constants struct {
	Permissions Permissions
}

Constants structure for storing constants application wide

func Const

func Const() Constants

Const returns a Constants struct with populated fields

type LoginResponse

type LoginResponse struct {
	JWT          string `json:"jwt"`
	RefreshToken string `json:"refresh_token"`
}

LoginResponse responds with this type when login is successful

type MetricPermissions

type MetricPermissions struct {
	View string
}

MetricPermissions permissions related to metric

type NewRegistration

type NewRegistration struct {
	Token string `json:"token"`
}

NewRegistration used for making a registration request

type NewUser

type NewUser struct {
	Email       string   `json:"email"`
	Password    string   `json:"password"`
	Permissions []string `json:"permissions"`
}

NewUser for creating a new user

func (NewUser) Ok

func (user NewUser) Ok() bool

Ok returns if user is valid

type NotificationPermissions

type NotificationPermissions struct {
	Create string
	View   string
	Delete string
}

NotificationPermissions permissions related to notifications

type Permission

type Permission struct {
	List string
}

Permission permission related permissions

type Permissions

type Permissions struct {
	Sudo          string
	User          UserPermission
	Permissions   Permission
	Notifications NotificationPermissions
	Metrics       MetricPermissions
}

Permissions store all available types of permission this application supports

type RefreshTokenHandlerResponse

type RefreshTokenHandlerResponse struct {
	JWT string `json:"jwt"`
}

RefreshTokenHandlerResponse is used when a refresh token is requested

type RegistrationResponse

type RegistrationResponse struct {
	Status string `json:"status"`
}

RegistrationResponse response for registration request

type RequestHelper

type RequestHelper interface {
	GetIPAddress(r *http.Request) string
}

RequestHelper interface to implement to satisfy as a Request Helper for this application

type Server

type Server struct {
	Logger    logger.Client
	Db        db.DB
	Redis     redis.Client
	Pushy     pushy.IPushyClient
	ReqHelper RequestHelper
	Jwt       jwt.Manager
}

Server is a global struct which holds implementation of different things application depends on. One can think of this as dependency container

func (Server) CreateUser

func (s Server) CreateUser() http.HandlerFunc

CreateUser handler used for creating new users

func (*Server) DeleteSession

func (s *Server) DeleteSession() http.HandlerFunc

DeleteSession deletes a session, used for logging out

func (*Server) ErrorResponse

func (s *Server) ErrorResponse(w http.ResponseWriter, r *http.Request, statusCode int, message string)

ErrorResponse util method to indicate failure

func (Server) GetUser

func (s Server) GetUser() http.HandlerFunc

GetUser to get information about a user

func (*Server) ListPermissions

func (s *Server) ListPermissions() http.HandlerFunc

ListPermissions is handler for listing permissions

func (Server) ListUsers

func (s Server) ListUsers() http.HandlerFunc

ListUsers used for listing all users

func (*Server) LoginHandler

func (s *Server) LoginHandler() http.HandlerFunc

LoginHandler handles login requests

func (*Server) RefreshTokenHandler

func (s *Server) RefreshTokenHandler() http.HandlerFunc

RefreshTokenHandler is used to refresh token

func (*Server) RefreshTokensList

func (s *Server) RefreshTokensList() http.HandlerFunc

RefreshTokensList returns list of refresh token associated with a user

func (*Server) RegisterHandler

func (s *Server) RegisterHandler() http.HandlerFunc

RegisterHandler is handler for registration requests

func (*Server) SuccessResponse

func (s *Server) SuccessResponse(w http.ResponseWriter, r *http.Request, statusCode int, message string)

SuccessResponse util method to indicate success

func (Server) UpdateUser

func (s Server) UpdateUser() http.HandlerFunc

UpdateUser to update information about user

func (Server) UserAvailability

func (s Server) UserAvailability() http.HandlerFunc

UserAvailability for checking if a email is already taken

type SimpleResponse

type SimpleResponse struct {
	Success bool   `json:"success"`
	Message string `json:"message"`
}

SimpleResponse is used when our handler wants to responds with simple boolean type information, like success, or fail

type UserAvailabilityRequest

type UserAvailabilityRequest struct {
	Email string `json:"email"`
}

UserAvailabilityRequest used for making request asking if email is available

type UserAvailabilityResponse

type UserAvailabilityResponse struct {
	Available bool `json:"available"`
}

UserAvailabilityResponse is used to respond for availability requests

type UserPermission

type UserPermission struct {
	List   string
	Create string
	Edit   string
	Delete string
}

UserPermission to store constants related to user permission