go-api

README

go-api

A typed API builder project to remove a bunch of boilerplate and repetition from golang API projects. This wires together a bunch of common dependencies, uses some reflection based magic to provide typed API functions and common error handling, and is intended to encode some best practices in API security.

Status

Overview

• core collects components and exposes the user API
• formats provide format encoding/decoding functions
• options provide base api server options and option parsing
• plugins provide plugins for meta analysis of the API implementation
• security provide security extensions for the API implementation
• servers provide base server handling (ie. http server, AWS lambda)
• wrappers provide wrapping functions for typed api endpoints

Usage

Install with go get github.com/ryankurte/go-api.

Create an application options object that inherits from options.Base and load with options.Parse(&o). Options are parsed using jessevdk/go-flags.

import (
    "github.com/ryankurte/go-api/lib/options"
)

type AppConfig struct {
    options.Base
    ...
}

...

o := AppConfig{}
err := options.Parse(&o)
if err != nil {
    os.Exit(0)
} 

Create a base application context with type handlers and a base api.API router, the attach handlers to the API router.

Handler functions support input parameters:

• (ctx ContextType)
• (ctx ContextType, i InputType)
• (ctx ContextType, i InputType, http.header)

And output parameters:

• (OutputType, error)
• (OutputType, int, error)
• (OutputType, int, http.Header, error)

Where ContextType, InputType and OutputType are user defined structs and int is a http.Status code. Input and output types are validated after decoding and prior to encoding using asaskevich/govalidator. The underlying mux is provided by gocraft/web.

import (
    "github.com/ryankurte/go-api/lib/options"
)

type AppContext struct {
	...
}

func (c *AppContext) FakeEndpoint(a AppContext, i Request) (Response, error) {
	...
}

ctx := AppContext{"Whoop whoop"}
api, err := api.New(ctx, &o.Base)
if err != nil {
    log.Print(err)
    os.Exit(-1)
}

err = api.RegisterEndpoint("/", "POST", (*AppContext).FakeEndpoint)

You can then launch a server with api.Run() and exit wth api.Close().

Check out example.go for a working example.

---

If you have any questions, comments, or suggestions, feel free to open an issue or a pull request.