/rest-api

A place to start when creating a rest api in go

Primary LanguageGo

REST API base template

To add endpoints

  • Add a new file.go in the routes that will define your group of endpoints
  • The cleanest way I found is to write an endpoint func that will return an endpoint object
  • Then write a Handler func to be setup in the Endpoint, which will do the work for the endpoint
  • You need to give your endpoint a path, method, content-type, and if needed, a request body and/or the response body
    • The path must start with a forward slash '/' paths are build as follows
    • /{version}/{group}/{endpoint.path} (trailing slashes are dropped)
  • You need to a setup func to add the endpoints to the api config
  • You will also need to add your setup to the InitRoutes() that the config setup calls

setup func example to add endpoints to the setup

func Setup() {
	setup.AddEndpoints(
		GetKittensEP(),
		KittenEP(),
		RMKittenEP(),
		AddKittnEP(),
	)
}

routes func that gets run by the config setup

// Add all route initializations here
func InitRoutes() {
	root.Setup()
	kittns.Setup()
	// ... add setup functions here
}
  • Write a func that returns an endpoint object to setup a new endpoint
  • Path should always start with a forward slash '/'
  • Name, Path, and Method are required for every endpoint
  • With no Version, or Group the root path is used
  • If you have url params i.e., /{url_path_value}
    • URLParams are required to define the param (for the api documentation)

endpoint func example

func MyEndpoint() Endpoint {
	return setup.Endpoint{
		Name:         "Get a Specific Kittn",
		Version:      "v1",
		Group:        "kittns",
		Path:         "/{id}",
		Method:       setup.GET,
		ResponseType: setup.ContentJSON,
		ResponseBody: Kitten{ID: 1, Name: "Fluffums", Breed: "calico", Fluffy: 6, Cute: 7}, // example for docs
		Description:  "This endpoint retrieves a specific kittn",
		HandlerFunc:  GetKitten,
		URLParams: []setup.Param{
			{Name: "id", Description: "the id for a kittn"},
		},
	}
}
  • Write a HandlerFunc to handle your request
    • then return the data needed for the endpoint
      • return an error if there is a problem
        • the error handler will then return the error to the user and log the actual error
// Home is an setup.Endpoint handler func example for the root / path
func Home(w http.ResponseWriter, r *http.Request) error {
	Respond(w, struct {
		AppName string         `json:"app_name"`
		Version version.Struct `json:"build_info"`
	}{
		AppName: "rest-api",
		Version: version.JSON(),
	}, true)
	return nil
}

API Documentation

  • the api docs are built from a markdown file
  • the app will use a template to re-write the markdown
  • slate will then generate api docs based on the markdown file
  • run make docs for linux and .\make.ps1 -docs for windows
    • powershell is required on windows to run the windows script
    • docker compose is required to run the slate build
  • run make for mac/linux and .\make.ps1 on windows
    • this will build the binary
  • after the docs are built, running the api will serve the docs