Adrien Marquès 4e51d59f2f | ||
---|---|---|
checker | ||
clifmt | ||
cmd/aicra | ||
config | ||
err | ||
implement | ||
middleware | ||
multipart | ||
request | ||
.gitignore | ||
LICENSE | ||
README.md | ||
server.go | ||
types.go | ||
util.go |
README.md
aicra: all-in-config REST API
Aicra is a self-working framework coded in Go that allows anyone to create a fully featured REST API. It features :
-
type checking
-
authentication management
-
rich argument management (url slash-separated, urlencoded, form-data, json)
-
nested routes
-
request and response interfaces
-
a project builder (cf. aicra)
-
Optional arguments and default values
-
...
It is based over some of the following concepts.
concept | explanation |
---|---|
meaningful defaults | Defaults and default values work without further understanding |
config-driven | Avoid information duplication. Automate anything that can be without losing control. Have one configuration that summarizes the whole project, its behavior and its automation flow. |
A working example is available here
1. Installation
You need a recent machine with go
installed.
This package has not been tested under the version 1.10.
(1) Installation
Run the following command to fetch and install the package :
go get -u git.xdrm.io/go/aicra
It should now be available locally and available for your imports.
You should then install the project builder to help you manage your projects, run the following command :
go install git.xdrm.io/go/aicra/cmd/aicra
The executable aicra
will be placed into your $GOPATH/bin
folder, if added to your environment PATH it should be available as a standalone command in your terminal. If not, you can simply run $GOPATH/bin/aicra
to use the command or create a symlink into /usr/local/bin
or the PATH folder of your choice for less characters to type.
2. Setup a project
To create a project using aicra, simply create an empty folder. Then you'll have to create a manifest.json
file containing your API description. To write your manifest file, follow this example.
(1) Controllers
For each uri, you'll have to place your implementation into the local root
folder following the following naming convention : add i.go
at the end of the route.
Example -
/path/to/some/uri
will be implemented in the ./root local folder inside the file :/path/to/some/urii.go
.
A fully working example is available here.
(2) Custom types
If you want to create custom types for the type checker or override built-in types place them inside the ./custom-types
folder. You can check what structure to follow by looking at the built-in types.
3. Build your project
After each controller or custom type edition, you'll have to rebuild the project. This can be achieved through the command-line builder.
Usage is aicra [options] /path/to/your/project
.
Options:
-
-c controller/path
- overrides the default controllers path ; default is./root
-
-t custom/types
- overrides the default custom types path ; default is./custom-types
4. Main in go
The main program is pretty small, it is as followed :
package main
import (
"os"
"git.xdrm.io/go/aicra"
)
func main() {
// 1. init with manifest file
server, err := aicra.Init("manifest.json")
if err != nil {
fmt.Printf("cannot load config : %s\n", err)
os.Exit(1)
}
// 2. Launch server
fmt.Printf("[Server up] 0.0.0.0:4242\n")
err = server.Launch(4242)
if err != nil {
fmt.Printf("[FAILURE] server failed : %s\n", err)
os.Exit(1)
}
}
changelog
- human-readable json configuration
- nested routes (i.e.
/user/:id:
and/user/post/:id:
) - nested URL arguments (i.e.
/user/:id:
and/user/:id:/post/:id:
) - useful http methods: GET, POST, PUT, DELETE
- manage URL, query and body arguments:
- multipart/form-data (variables and file uploads)
- application/x-www-form-urlencoded
- application/json
- required vs. optional parameters with a default value
- parameter renaming
- generic authentication system (i.e. you can override the built-in one)
- generic type check (i.e. implement custom types alongside built-in ones)
- built-in types
any
- wildcard matching all valuesint
- any number (e.g. float, int, uint)string
- any textvarchar(min, max)
- any string with a length betweenmin
andmax
<a>
- array containing only elements matchinga
type<a:b>
- map containing only keys of typea
and values of typeb
(a or b can be ommited)
- generic controllers implementation (shared objects)
- response interface