update readme + add badges
This commit is contained in:
parent
0ab05816ea
commit
0046c165b2
64
README.md
64
README.md
|
|
@ -1,6 +1,7 @@
|
|||
# aicra: all-in-config REST API
|
||||
|
||||
# | aicra |
|
||||
|
||||
[](https://golang.org/doc/go1.10)
|
||||
[](https://goreportcard.com/report/git.xdrm.io/go/aicra)
|
||||
|
||||
**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 through middlewares, file upload, rich argument parsing (*i.e. url slash-separated, urlencoded, form-data, json*), nested routes, project builder (*i.e. aicra*), etc.
|
||||
|
||||
|
|
@ -14,13 +15,17 @@ This framework is based over some of the following concepts.
|
|||
| 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](https://git.xdrm.io/example/aicra)
|
||||
|
||||
|
||||
|
||||
#### 1. Installation
|
||||
#### Table of contents
|
||||
|
||||
[TOC]
|
||||
|
||||
|
||||
|
||||
#### I. Installation
|
||||
|
||||
You need a recent machine with `go` installed.
|
||||
|
||||
|
|
@ -28,7 +33,7 @@ You need a recent machine with `go` installed.
|
|||
|
||||
|
||||
|
||||
##### (1) Download and install the package
|
||||
##### 1. Download and install the package
|
||||
|
||||
```bash
|
||||
$ go get -u git.xdrm.io/go/aicra
|
||||
|
|
@ -38,7 +43,7 @@ It should now be available locally and available for your imports.
|
|||
|
||||
|
||||
|
||||
##### (2) Compile the command-line builder
|
||||
##### 2. Compile the command-line builder
|
||||
|
||||
You should then compile the project builder to help you manage your projects.
|
||||
|
||||
|
|
@ -52,10 +57,14 @@ $ go install git.xdrm.io/go/aicra/cmd/aicra
|
|||
|
||||
|
||||
|
||||
#### 2. Setup a project
|
||||
#### II. Setup a project
|
||||
|
||||
The default project structure for **aicra** is as follows :
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
```
|
||||
├── main.go - the entry point
|
||||
├── manifest.json - the configuration file
|
||||
|
|
@ -69,7 +78,7 @@ In order for your project to be run, each controller, middleware and type have t
|
|||
|
||||
|
||||
|
||||
##### (1) Configuration
|
||||
##### 1. Configuration
|
||||
|
||||
The whole project behavior is described inside the `manifest.json` file. For a better understanding of the format, take a look at this working [template](https://git.xdrm.io/example/aicra/src/master/manifest.json). This file contains information about :
|
||||
|
||||
|
|
@ -81,7 +90,7 @@ The whole project behavior is described inside the `manifest.json` file. For a b
|
|||
|
||||
|
||||
|
||||
##### (2) Controllers
|
||||
##### 2. Controllers
|
||||
|
||||
For each route, you'll have to place your implementation into the `controller` folder following the naming convention : add `/i.go` at the end of the route.
|
||||
|
||||
|
|
@ -91,7 +100,7 @@ A fully working example is available [here](https://git.xdrm.io/example/aicra).
|
|||
|
||||
|
||||
|
||||
##### (3) Middlewares
|
||||
##### 3. Middlewares
|
||||
|
||||
In order for your project to manage authentication, the best solution is to create middlewares, there are programs that updates a *Scope* according to internal or persistent (*i.e.* database) information and the actual http request. They are all run before each request it routed by aicra. The scope are used to match the `scope` field in the configuration file and automatically block non-authed requests. Scopes can also be used for implementation-specific behavior.
|
||||
|
||||
|
|
@ -105,7 +114,7 @@ Each middleware must be directly inside the `middleware` folder.
|
|||
|
||||
|
||||
|
||||
##### (4) Custom types
|
||||
##### 4. Custom types
|
||||
|
||||
In your configuration you will have to use built-in types (*e.g.* int, any, varchar), but if you want project-specific ones, you can add your own types inside the `type` folder. You can check what structure to follow by looking at the [built-in types](https://git.xdrm.io/go/aicra/src/master/checker/default).
|
||||
|
||||
|
|
@ -115,7 +124,7 @@ Each type must be inside a unique package directly inside the `type` folder. The
|
|||
|
||||
|
||||
|
||||
#### 3. Build your project
|
||||
#### III. Build your project
|
||||
|
||||
After each controller, middleware or type edition, you'll have to rebuild the project. This can be achieved through the command-line builder.
|
||||
|
||||
|
|
@ -139,41 +148,25 @@ The output should look like
|
|||
|
||||
.
|
||||
|
||||
#### 4. Main
|
||||
#### IV. Main
|
||||
|
||||
The main program is pretty small, it is as followed :
|
||||
The main default program is pretty small as below :
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"git.xdrm.io/go/aicra"
|
||||
)
|
||||
import "git.xdrm.io/go/aicra"
|
||||
|
||||
func main() {
|
||||
|
||||
// 1. init with manifest file
|
||||
server, err := aicra.New("manifest.json")
|
||||
if err != nil {
|
||||
log.Fatalf("cannot load config : %s\n", err)
|
||||
}
|
||||
if err != nil { return }
|
||||
|
||||
fmt.Printf("[Server up] 0.0.0.0:4242\n")
|
||||
// 2. Launch server
|
||||
err = server.Listen(4242)
|
||||
if err != nil {
|
||||
log.Fatalf("[FAILURE] server failed : %s\n", err)
|
||||
}
|
||||
server.Listen(4242)
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
##### changelog
|
||||
#### V. Change Log
|
||||
|
||||
- [x] human-readable json configuration
|
||||
- [x] nested routes (*i.e. `/user/:id:` and `/user/post/:id:`*)
|
||||
|
|
@ -196,3 +189,4 @@ func main() {
|
|||
- [ ] `<a:b>` - map containing **only** keys of type `a` and values of type `b` (*a or b can be ommited*)
|
||||
- [x] generic controllers implementation (shared objects)
|
||||
- [x] response interface
|
||||
- [ ] devmode watcher : watch manifest, watch plugins to compile + hot reload them
|
||||
Loading…
Reference in New Issue