Categorygrest.dev/grest
modulepackage
0.0.0-20240515073044-6c50445207c2
Repository: https://github.com/zahir-core/grest.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
45
Dependents
2
Files
4.8k SLOC

# README

GREST

An instant, full-featured, and scalable REST APIs framework with go. Designed to make rapid development easy with clean code and best performance.

It takes care of a lot of the complexities of developing REST APIs so you can focus on the business logic of your app. Build prototypes in minutes and production-ready apps in days. Seriously.

GREST gives you the structure to build service oriented apps from day one. When you eventually need to split your app into microservices it’s an easy transition.

Feature

  • Getting Started
    • Prerequisites
    • CLI
    • Directory Structure
    • Configuration
    • Testing
    • Deployment
  • Basic
    • Routing
    • Middleware
    • Request
    • Response
    • Model
    • Validation
    • Error Handling
    • Logging
  • Database
    • Connecting to Database
    • CRUD
    • Query Builder
    • Migration
    • Seed
    • Cache
  • Security
    • Authentication
    • Authorization
    • Encryption
    • Hashing
    • JWT
    • OAuth
  • Client
    • HTTP Client
    • gRPC Client
  • Notification
    • Mail
    • Telegram
    • Slack
  • More
    • OpenAPI Documentation
    • Frontend Integration
    • File Storage
    • Translation
    • Websocket
    • gRPC Server
    • Scheduling
    • Queue
    • Event

Getting Started

Coming Soon...

Inspired By

Originally, GREST inspired by the following frameworks, however we did it with a different approach, complementing its features, making it easier to use and more flexible with optimal performance and of course with Go ways.

  • Feathers — A framework for real-time applications and REST APIs.
  • LoopBack — A highly extensible Node.js and TypeScript framework for building APIs and microservices.
  • Laravel — The PHP Framework for Web Artisans.
  • Django — A high-level Python web framework that encourages rapid development and clean, pragmatic design.

Library

GREST is REST APIs framework with a "batteries-included" philosophy, it means that GREST comes with most of the libraries and tools required for common use cases, out of the box, so you can focus on the business logic of your application instead of choosing libraries and tools or creating your own. Thanks to the following libraries and tools that help GREST realize that philosophy :

  • Fiber — An Express-inspired web framework written in Go.
  • GORM — The fantastic ORM library for Golang.
  • go-redis — Redis client for Golang.
  • Package validator — Package validator implements value validations for structs and individual fields based on tags.
  • zerolog — Zero Allocation JSON Logger.
  • @stoplight/elements — Beautiful API documentation powered by OpenAPI and Markdown.
  • MinIO Go Client SDK — MinIO Go Client SDK for Amazon S3 Compatible Cloud Storage
  • etc

Contribute

You can help to deliver a better GREST by the following ways:

  • Reporting issues
  • Suggesting new features or enhancements
  • Improve/fix documentation
  • Sending a pull request The core team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation. Pull request should have:
    • Test case
    • Documentation
    • Example (If it makes sense)
  • You can also contribute by:
    • Add a GitHub Star to the project.
    • Tweet about the project on your Twitter.
    • Write a review or tutorial on your youtube channel or personal blog.

By contributing to GREST, you agree that your contributions will be licensed under its MIT license.

License

GREST officialy created, used, and maintained by Zahir Core Team. GREST is free and open-source software licensed under the MIT License.

# Functions

Find finds all records matching given conditions conds from model and query params.
Fmt format log with attribute for example : log.Fmt("text", log.Bold, log.Red) output (text with bold red foreground) : \x1b[1;31mtext\x1b[0m.
FormatFile formats struct tags in Go source files.
LoadEnv loads environment variable values into corresponding variables.
NewCrypto initializes a new Crypto instance with optional key values.
NewError returns an error with the specified status code, message, and optional detail.
NewHttpClient creates a new HttpClient instance with the provided HTTP method and URL.
NewJSON creates a new JSON instance with provided data and optional options.
NewMockDB creates a new mock database and returns the gorm.DB instance.
StartupMessage generates and prints the startup message for the server.

# Constants

Background text colors.
Background text colors.
Background text colors.
Background text colors.
Background Hi-Intensity text colors.
Background Hi-Intensity text colors.
Background Hi-Intensity text colors.
Background Hi-Intensity text colors.
Background Hi-Intensity text colors.
Background Hi-Intensity text colors.
Background Hi-Intensity text colors.
Background Hi-Intensity text colors.
Background text colors.
Background text colors.
Background text colors.
Background text colors.
Foreground text colors.
Base attributes.
Base attributes.
Foreground text colors.
Base attributes.
Base attributes.
Base attributes.
Foreground text colors.
Base attributes.
Foreground text colors.
Foreground Hi-Intensity text colors.
Foreground Hi-Intensity text colors.
Foreground Hi-Intensity text colors.
Foreground Hi-Intensity text colors.
Foreground Hi-Intensity text colors.
Foreground Hi-Intensity text colors.
Foreground Hi-Intensity text colors.
Foreground Hi-Intensity text colors.
Base attributes.
Foreground text colors.
Foreground text colors.
Base attributes.
Base attributes.
Base attributes.
Foreground text colors.
Foreground text colors.
The Accept-Language request HTTP header indicates the natural language and locale that the client prefers.
Version is the current version of the GREST.

# Variables

No description provided by the author
No description provided by the author
No description provided by the author
DisableFmt defines if the output is colorized or not.
Output defines the standard output of the print functions.
No description provided by the author
GREST support a common way for pagination, selecting fields, filtering, sorting, searching and other using URL query params this is the default of query parameter setting, you can override this with your own preferences.
QueryCast defines the delimiter used for casting data types in query parameters.
aggregation query params ex: /products?$select=$count:id => sql: select count(id) as "count.id" from products ex: /products?$select=$sum:sold => sql: select sum(sold) as "sum.sold" from products ex: /products?$select=$min:sold => sql: select min(sold) as "min.sold" from products ex: /products?$select=$max:sold => sql: select max(sold) as "max.sold" from products ex: /products?$select=$avg:sold => sql: select avg(sold) as "avg.sold" from products.
GREST support a common way for pagination, selecting fields, filtering, sorting, searching and other using URL query params this is the default of query parameter setting, you can override this with your own preferences.
Sets the default number of items when $per_page is not set.
ex: /contacts?$is_disable_pagination=true => sql: select * from contacts.
exclude query params setting for First method and Find method, by default query for all fields defined in struct is executed except for fields that explicitly hide by db:"-,hide" struct tags to exclude some fields from executed in query you can hide it using QueryExclude it can be setted by multiple fields, separated by comma ex: /contacts?$exclude=families,friends,phones => exclude fields: families, friends, and phones.
field query params setting useful for filter, select or sort using another field ex: /products?qty_available=$field:qty_on_hand => sql: select * from products where qty_available = qty_on_hand ex: /products?qty_on_order.$gt=$field:qty_available => sql: select * from products where qty_on_order > qty_available.
grouping query params setting ex: /products?$group=category.id => sql: select category_id from products group by category_id ex: /products?$group=category.id&$select=category.id,$avg:sold => sql: select category_id, avg(sold) as "avg.sold" from products group by category_id ex: /products?$group=category.id&$select=category.id,$sum:sold&$sum:sold.$gt=0 => sql: select category_id, sum(sold) as "sum.sold" from products group by category_id having sum(sold) > 0 ex: /products?$group=category.id&$select=category.id,$sum:sold&$sort:-$sum:sold => sql: select category_id, sum(sold) as "sum.sold" from products group by category_id order by sum(sold) desc.
include query params setting for First method, by default query for all array fields is executed but for Find method, by default query for array fields (has many or many to many) is not executed for optimum performance to execute array fields query on Find method, you can add using QueryInclude it can be setted by multiple fields, separated by comma if QueryInclude setted to all, query for all array fields is executed ex: /contacts?$include=families,friends,phones => include array fields: families, friends, and phones ex: /contacts?$include=all => include all array fields ex: /contacts/{id} => same as /contacts?id={id}&$include=all.
ex: /contacts?$per_page=20 => sql: select * from contacts limit 20.
GREST support a common way for pagination, selecting fields, filtering, sorting, searching and other using URL query params this is the default of query parameter setting, you can override this with your own preferences.
Sets the maximum allowed number of items per page (even if the QueryLimit query parameter is set higher).
GREST support a common way for pagination, selecting fields, filtering, sorting, searching and other using URL query params this is the default of query parameter setting, you can override this with your own preferences.
ex: /contacts?$offset=20 => sql: select * from contacts offset 20.
ex: /contacts?gender.$eq=male => sql: select * from contacts where gender = 'male' => same with /contacts?gender=male.
ex: /contacts?age.$gt=18 => sql: select * from contacts where age > 18.
ex: /contacts?age.$gte=21 => sql: select * from contacts where age >= 21.
ex: /contacts?age.$in=17,21,34 => sql: select * from contacts where age in (17,21,34).
ex: /contacts?name.$ilike=john% => sql: select * from contacts where lower(name) like lower('john%').
ex: /contacts?name.$nilike=john% => sql: select * from contacts where lower(name) not like lower('john%').
ex: /contacts?name.$like=john% => sql: select * from contacts where name like 'john%'.
ex: /contacts?age.$lt=17 => sql: select * from contacts where age < 17.
ex: /contacts?age.$lte=15 => sql: select * from contacts where age <= 15.
ex: /contacts?phone.$ne=null => sql: select * from contacts where phone is not null.
ex: /contacts?age.$nin=17,21,34 => sql: select * from contacts where age not in (17,21,34).
ex: /contacts?name.$nlike=john% => sql: select * from contacts where name not like 'john%'.
or query params setting ex: /contacts?$or=gender=female||age.$lt=10&$or=is_salesman=true||is_employee=true => sql: select * from contacts where (gender = 'female' or age < 10) and (is_salesman = '1' or is_employee = '1').
GREST support a common way for pagination, selecting fields, filtering, sorting, searching and other using URL query params this is the default of query parameter setting, you can override this with your own preferences.
ex: /contacts?$page=3&per_page=10 => sql: select * from contacts limit 10 offset 20.
search query params setting ex: /contacts?$search=code,name=john => sql: select * from contacts where (lower(code) = lower('john') or lower(name) = lower('john')).
selection query params setting it can be setted by multiple fields, separated by comma ex: /contacts?$select=id,code,name => sql: select id, code, name from contacts.
sorting query params setting default is ascending it can be setted by multiple fields, separated by comma add prefix - to sort descending add sufix :i to sort case insensitive ex: /contacts?$sort=gender,-age,-name:i => sql: select * from contacts order by gender, age desc, lower(name) desc.
GREST support a common way for pagination, selecting fields, filtering, sorting, searching and other using URL query params this is the default of query parameter setting, you can override this with your own preferences.

# Structs

Cache is a cache utility that manages caching using redis or in-memory data.
Crypto is a crypto utility for managing cryptographic operations.
DB is a DB utility to manage database connections, migrations, and seeders.
DBConfig represents the configuration for a database connection.
DBQuery DBQuery definition for querying with model & query params.
Error is an implementation of the error interface with trace and other details.
FileFormatter provides methods to format struct tags in Go source files.
HttpClient is a utility to perform HTTP requests and manage various request parameters.
JSON is a struct that handles JSON data manipulation.
JSONSeparator defines separators for flattening JSON keys.
model struct tag : json : - dot notation field to be parsed to multi-dimensional json object - also used for alias field when query to db db : - field to query to db - add ",group" to group the field - add ",hide" to hide the field on api response gorm : - field option for main table of the struct - the details can be found at : https://gorm.io/docs/models.html#Fields-Tags - if the field is not field of main table of the struct in the database, gorm must be setted to "-" validate : - validation tag to validate the data - "required" tag will be used as "required" on OpenAPI Specification - "oneof" tag will be used as "enum" on OpenAPI Specification - "max" tag will be used as "maximum" or "maxLength" on OpenAPI Specification based on value type - "min" tag will be used as "minimum" or "minLength" on OpenAPI Specification based on value type - the details can be found at : https://pkg.go.dev/github.com/go-playground/validator/v10 title : - used as "title" on OpenAPI Specification note : - used as "description" on OpenAPI Specification default : - used for the default value when insert to db - used as "default" on OpenAPI Specification example : - used as "example" on OpenAPI Specification.
NullBool is a nullable bool.
NullDate is a nullable date.
NullDateTime is a nullable time.Time.
NullFloat64 is a nullable float64.
NullInt64 is a nullable int64.
NullJSON represents a nullable JSON value.
NullString is a nullable string.
NullText represents a nullable text value.
NullTime is a nullable time.
NullUnixTime is a nullable date.
NullUUID represents a nullable UUID value.
OpenAPI represents the OpenAPI specification structure.
OpenAPIContact represents the contact information in the OpenAPI info section.
OpenAPIExternalDoc represents an external documentation link in the OpenAPI specification.
OpenAPIInfo represents the information section of the OpenAPI specification.
OpenAPILicense represents the license information in the OpenAPI info section.
OpenAPIOperation represents an OpenAPI operation object.
No description provided by the author
String represents utility functions for string manipulation.
StructTag represents a key-value pair within a struct tag.
Telegram is an utility to send telegram message using the Telegram API.
Translator handles translation of messages based on language keys.
Validator struct wraps the validator.Validate and provides additional methods for validation.

# Interfaces

No description provided by the author
MigrationTable is an interface for migration-related tables.
ModelInterface defines the methods that a model must implement.
OpenAPIOperationInterface defines the interface for completing the operation object of an endpoint in the OpenAPI document.
OpenAPISchemaComponent defines the interface for components with OpenAPI schemas.
SeederTable is an interface for seeder-related tables.
SettingTable is an interface for setting-related tables.
Table is an interface for database table models.

# Type aliases

MapSlice of map items.