easyrest

README

GO Fiber Easy Rest API With GORM

GORM (https://gorm.io) is an amazing DB ORM for go. It lets you define a CRUD api from just the type structure. go-easyrest attempts the same, exposing the same GORM object as a REST/CRUD API with just one line of code.

Installation

go get github.com/pilotso11/go-easyrest

Usage

type Employee struct {
	gorm.Model
	Name       string
	EmployeeNo int
	Department string
}

// connect to your DB
// Create your gorm data model
err = db.AutoMigrate(&Employee{})

// Setup Fiber
app := fiber.New()

// Create the REST API
easyrest.RegisterApi(apiV1, db, "employees", easyrest.DefaultOptions[Employee, Employee]())

fiber.Serve("localhost:8080")

With this single line a the following are exposed:

• GET http://localhost:8080/employees - to get all employees
• POST http://localhost:8080/employees/filter - to search for employees (exact match only at the moment)
• POST http://localhost:8080/employees/ - to create a single employee
• GET http://localhost:8080/employees/ID - to get a single employee
• PUT http://localhost:8080/employees/ID - to update a single employee
• DELETE http://localhost:8080/employees/ID - to delete a single employee

More advanced uses allow for custom DTO types, authentication, limit of functions and exposing child object lists. Look in /examples .

Documentation

Index

• func RegisterAPI[T any, D any](api fiber.Router, genericApi Api[T, D])
• func RegisterApi[T any, D any](app fiber.Router, db *gorm.DB, path string, options Options[T, D])
• type Action
• type Api
• type Options
  • func DefaultOptions[T any, D any]() Options[T, D]
• type SubEntity

Functions

func RegisterAPI

func RegisterAPI[T any, D any](api fiber.Router, genericApi Api[T, D])

func RegisterApi

func RegisterApi[T any, D any](app fiber.Router, db *gorm.DB, path string, options Options[T, D])

RegisterApi exposes an api underneath the app route using path and exposing objects of T. Objets of T are managed in db using GORM including mutations as enabled in Options. There must be a single string key field in the T option exposed as the tag `rest:"key"`. Child objects can be exposed either directly in the json by making them present in the Dto type or as sub-paths exposed as path/:id/field if specified using the tag `rest:"child"`. If exposed as child paths the child objects are read only. If exposed in the json then they will be part of the GORM mutation actions.

Types

type Action

type Action uint8

const (
	ActionGetAll Action = iota
	ActionGetOne
	ActionMutate
	ActionCreate
	ActionDelete
)

type Api

type Api[T any, D any] struct {
	Path        string                                            // The path of the api under the parent
	Find        func(key string) (T, bool)                        // Find one method
	FindAll     func() []T                                        // Find all method
	Search      func(D) []T                                       // Search using D as a filter
	Mutate      func(T, D) (T, error)                             // Mutation function for "PUT".  If nil, no mutation is exposed
	Create      func(D) (T, error)                                // Create function for "PUT".  If nil, creation is not exposed
	Delete      func(T) (T, error)                                // // Mutation function for "DELETE", if nil, no mutation is exposed
	SubEntities []SubEntity[T, D]                                 // SubEntities to expose as read only lists
	Dto         func(T) D                                         // Fill a DTO for T
	Validator   func(c *fiber.Ctx, action Action, item ...T) bool // Access check, T will be missing for aggregate functions or if the item is not found
}

Api is the easy rest/crud API for Fiber. Supply functions to find and mutate data objects and the Api will handle the rest implementation. The Api is defined by two generic types. The first, T, is the underlying dats type. The second, D, is a data transport type (DTO) used for the JSON in the API. The two types can be the same, but separating them gives additional flexibility to have different json transformations for internal and external API uses. See examples.

type Options

type Options[T any, D any] struct {
	Delete    bool                                              // Enable delete
	Mutate    bool                                              // Enable mutate
	Create    bool                                              // Enable create
	Validator func(c *fiber.Ctx, action Action, item ...T) bool // Validation function, item is empty if this is a find all query or an item is not found
}

Options for the exposed GORM backed REST API. Delete, Mutate and Create are available to enable or disable mutation options. If all are false then the API is read only. A validation function is also optional. If the Validator returns falls 301 (unauthorized) is returned to ensure object presence is not leaked. Two Types are specified, T and D. T is the storage type, and D is a DTO type. They can be the same. Fields from T are copied to identically named fields in D before being sent on the REST API as json. Inbound the reverse happens on any Mutate or Create.

func DefaultOptions

func DefaultOptions[T any, D any]() Options[T, D]

DefaultOptions returns a basic configuration allowing all rest operations and with no authentication

type SubEntity

type SubEntity[T any, D any] struct {
	SubPath string
	Get     func(item T) []any
}