update: readme
This commit is contained in:
parent
11aa9f0a0f
commit
546130cfd0
GPG Key ID:
D75243CA236D825E
339
README.md
339
README.md
|
|
@ -6,191 +6,282 @@
|
||||||
[](https://godoc.org/git.xdrm.io/go/aicra)
|
[](https://godoc.org/git.xdrm.io/go/aicra)
|
||||||
[](https://drone.xdrm.io/go/aicra)
|
[](https://drone.xdrm.io/go/aicra)
|
||||||
|
|
||||||
|
----
|
||||||
|
|
||||||
Aicra is a *configuration-driven* REST API engine written in Go.
|
`aicra` is a lightweight and idiomatic API engine for building Go services. It's especially good at helping you write large REST API services that remain maintainable as your project grows.
|
||||||
|
|
||||||
Most of the management is done for you using a configuration file describing your API. you're left with implementing :
|
The focus of the project is to allow you to build a fully featured REST API in an elegant, comfortable and inexpensive way. This is achieved by using a configuration file to drive the server. The configuration format describes the whole API: routes, input arguments, expected output, permissions, etc.
|
||||||
- handlers
|
|
||||||
- optionnally middle-wares (_e.g. authentication, csrf_)
|
|
||||||
- and optionnally your custom type checkers to check input parameters
|
|
||||||
|
|
||||||
> A example project is available [here](https://git.xdrm.io/go/articles-api)
|
TL;DR: `aicra` is a fast configuration-driven REST API engine.
|
||||||
|
|
||||||
## Table of contents
|
Repetitive tasks is automatically processed by `aicra` from your configuration file, you just have to implement your handlers.
|
||||||
|
|
||||||
|
The engine automates :
|
||||||
|
- catching input data (_url, query, form-data, json, url-encoded_)
|
||||||
|
- handling missing input data (_required arguments_)
|
||||||
|
- handling input data validation
|
||||||
|
- checking for mandatory output parameters
|
||||||
|
- checking for missing method implementations
|
||||||
|
- checking for handler signature (input and output arguments)
|
||||||
|
|
||||||
|
> An example project is available [here](https://git.xdrm.io/go/articles-api)
|
||||||
|
|
||||||
|
### Table of contents
|
||||||
|
|
||||||
<!-- toc -->
|
<!-- toc -->
|
||||||
|
|
||||||
- [I/ Installation](#i-installation)
|
* [Installation](#installation)
|
||||||
- [II/ Usage](#ii-usage)
|
- [Usage](#usage)
|
||||||
* [1) Build a server](#1-build-a-server)
|
- [Create a server](#create-a-server)
|
||||||
* [2) API Configuration](#2-api-configuration)
|
- [Create a handler](#create-a-handler)
|
||||||
- [Definition](#definition)
|
- [Configuration](#configuration)
|
||||||
+ [Input Arguments](#input-arguments)
|
- [Global format](#global-format)
|
||||||
- [1. Input types](#1-input-types)
|
* [Input section](#input-section)
|
||||||
- [2. Global Format](#2-global-format)
|
+ [Format](#format)
|
||||||
- [III/ Change Log](#iii-change-log)
|
- [Example](#example)
|
||||||
|
- [Changelog](#changelog)
|
||||||
|
|
||||||
<!-- tocstop -->
|
<!-- tocstop -->
|
||||||
|
|
||||||
## I/ Installation
|
## Installation
|
||||||
|
|
||||||
You need a recent machine with `go` [installed](https://golang.org/doc/install). This package has not been tested under the version **1.14**.
|
You need a recent machine with `go` [installed](https://golang.org/doc/install). The package has not been tested under **go1.14**.
|
||||||
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go get -u git.xdrm.io/go/aicra/cmd/aicra
|
go get -u git.xdrm.io/go/aicra
|
||||||
```
|
```
|
||||||
|
|
||||||
The library should now be available as `git.xdrm.io/go/aicra` in your imports.
|
|
||||||
|
# Usage
|
||||||
|
|
||||||
|
|
||||||
## II/ Usage
|
#### Create a server
|
||||||
|
|
||||||
|
The code below sets up and creates an HTTP server from the `api.json` configuration.
|
||||||
### 1) Build a server
|
|
||||||
|
|
||||||
Here is some sample code that builds and sets up an aicra server using your api configuration file.
|
|
||||||
|
|
||||||
```go
|
```go
|
||||||
package main
|
package main
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"log"
|
"log"
|
||||||
"net/http"
|
"net/http"
|
||||||
"os"
|
"os"
|
||||||
|
|
||||||
"git.xdrm.io/go/aicra"
|
"git.xdrm.io/go/aicra"
|
||||||
"git.xdrm.io/go/aicra/api"
|
"git.xdrm.io/go/aicra/api"
|
||||||
"git.xdrm.io/go/aicra/datatype/builtin"
|
"git.xdrm.io/go/aicra/datatype/builtin"
|
||||||
)
|
)
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
|
builder := &aicra.Builder{}
|
||||||
|
|
||||||
builder := &aicra.Builder{}
|
// register available validators
|
||||||
|
builder.AddType(builtin.BoolDataType{})
|
||||||
|
builder.AddType(builtin.UintDataType{})
|
||||||
|
builder.AddType(builtin.StringDataType{})
|
||||||
|
|
||||||
// add datatypes your api uses
|
// load your configuration
|
||||||
builder.AddType(builtin.BoolDataType{})
|
config, err := os.Open("./api.json")
|
||||||
builder.AddType(builtin.UintDataType{})
|
if err != nil {
|
||||||
builder.AddType(builtin.StringDataType{})
|
log.Fatalf("cannot open config: %s", err)
|
||||||
|
}
|
||||||
|
err = builder.Setup(config)
|
||||||
|
config.Close() // free config file
|
||||||
|
if err != nil {
|
||||||
|
log.Fatalf("invalid config: %s", err)
|
||||||
|
}
|
||||||
|
|
||||||
config, err := os.Open("./api.json")
|
// bind your handlers
|
||||||
if err != nil {
|
builder.Bind(http.MethodGet, "/user/{id}", getUserById)
|
||||||
log.Fatalf("cannot open config: %s", err)
|
builder.Bind(http.MethodGet, "/user/{id}/username", getUsernameByID)
|
||||||
}
|
|
||||||
|
|
||||||
// pass your configuration
|
// build the handler and start listening
|
||||||
err = builder.Setup(config)
|
handler, err := builder.Build()
|
||||||
config.Close()
|
if err != nil {
|
||||||
if err != nil {
|
log.Fatalf("cannot build handler: %s", err)
|
||||||
log.Fatalf("invalid config: %s", err)
|
}
|
||||||
}
|
http.ListenAndServe("localhost:8080", handler)
|
||||||
|
|
||||||
// bind your handlers
|
|
||||||
builder.Bind(http.MethodGet, "/user/{id}", getUserById)
|
|
||||||
builder.Bind(http.MethodGet, "/user/{id}/username", getUsernameByID)
|
|
||||||
|
|
||||||
// build the server and start listening
|
|
||||||
server, err := builder.Build()
|
|
||||||
if err != nil {
|
|
||||||
log.Fatalf("cannot build server: %s", err)
|
|
||||||
}
|
|
||||||
http.ListenAndServe("localhost:8080", server)
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
If you want to use HTTPS, you can configure your own `http.Server`.
|
||||||
|
|
||||||
Here is an example handler
|
|
||||||
```go
|
```go
|
||||||
type req struct{
|
func main() {
|
||||||
Param1 int
|
server := &http.Server{
|
||||||
Param3 *string // optional are pointers
|
Addr: "localhost:8080",
|
||||||
}
|
TLSConfig: tls.Config{},
|
||||||
type res struct{
|
// aicra handler
|
||||||
Output1 string
|
Handler: handler,
|
||||||
Output2 bool
|
|
||||||
}
|
|
||||||
|
|
||||||
func myHandler(r req) (*res, api.Error) {
|
|
||||||
err := doSomething()
|
|
||||||
if err != nil {
|
|
||||||
return nil, api.ErrorFailure
|
|
||||||
}
|
}
|
||||||
return &res{}, api.ErrorSuccess
|
|
||||||
|
server.ListenAndServe()
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
### 2) API Configuration
|
#### Create a handler
|
||||||
|
|
||||||
The whole api behavior is described inside a json file (_e.g. usually api.json_). For a better understanding of the format, take a look at this working [template](https://git.xdrm.io/go/articles-api/src/master/api.json). This file defines :
|
The code below implements a simple handler.
|
||||||
|
```go
|
||||||
|
// "in": {
|
||||||
|
// "Input1": { "info": "...", "type": "int" },
|
||||||
|
// "Input2": { "info": "...", "type": "?string" }
|
||||||
|
// },
|
||||||
|
type req struct{
|
||||||
|
Input1 int
|
||||||
|
Input2 *string // optional are pointers
|
||||||
|
}
|
||||||
|
// "out": {
|
||||||
|
// "Output1": { "info": "...", "type": "string" },
|
||||||
|
// "Output2": { "info": "...", "type": "bool" }
|
||||||
|
// }
|
||||||
|
type res struct{
|
||||||
|
Output1 string
|
||||||
|
Output2 bool
|
||||||
|
}
|
||||||
|
|
||||||
|
func myHandler(r req) (*res, api.Err) {
|
||||||
|
err := doSomething()
|
||||||
|
if err != nil {
|
||||||
|
return nil, api.ErrFailure
|
||||||
|
}
|
||||||
|
return &res{"out1", true}, api.ErrSuccess
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If your handler signature does not match the configuration exactly, the server will print out the error and will not start.
|
||||||
|
|
||||||
|
The `api.Err` type automatically maps to HTTP status codes and error descriptions that will be sent to the client as json; client will then always have to manage the same format.
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": {
|
||||||
|
"code": 0,
|
||||||
|
"reason": "all right"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
The whole api behavior is described inside a json file (_e.g. usually api.json_). For a better understanding of the format, take a look at this working [configuration](https://git.xdrm.io/go/articles-api/src/master/api.json).
|
||||||
|
|
||||||
|
The configuration file defines :
|
||||||
- routes and their methods
|
- routes and their methods
|
||||||
- every input for each method (called *argument*)
|
- every input argument for each method
|
||||||
- every output for each method
|
- every output for each method
|
||||||
- scope permissions (list of permissions needed by clients)
|
- scope permissions (list of permissions required by clients)
|
||||||
- input policy :
|
- input policy :
|
||||||
- type of argument (_c.f. data types_)
|
- type of argument (_c.f. data types_)
|
||||||
- required/optional
|
- required/optional
|
||||||
- variable renaming
|
- variable renaming
|
||||||
|
|
||||||
#### Format
|
#### Global format
|
||||||
|
|
||||||
The root of the json file must be an array containing your requests definitions. For each, you will have to create fields described in the table above.
|
The root of the json file must feature an array containing your requests definitions. For each, you will have to create fields described in the table above.
|
||||||
|
|
||||||
| field path | description | example |
|
- `info`: Short description of the method
|
||||||
| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
- `in`: List of arguments that the clients will have to provide. [Read more](#input-arguments).
|
||||||
| `info` | A short human-readable description of what the method does | `create a new user` |
|
- `out`: List of output data that your controllers will output. It has the same syntax as the `in` field but optional parameters are not allowed.
|
||||||
| `scope` | A 2-dimensional array of permissions. The first dimension can be translated to a **or** operator, the second dimension as a **and**. It allows you to combine permissions in complex ways. | `[["A", "B"], ["C", "D"]]` can be translated to : this method needs users to have permissions (A **and** B) **or** (C **and** D) |
|
- `scope`: A 2-dimensional array of permissions. The first level means **or**, the second means **and**. It allows to combine permissions in complex ways.
|
||||||
| `in` | The list of arguments that the clients will have to provide. [Read more](#input-arguments). | |
|
- Example: `[["A", "B"], ["C", "D"]]` translates to : this method requires users to have permissions (A **and** B) **or** (C **and** D)
|
||||||
| `out` | The list of output data that will be returned by your controllers. It has the same syntax as the `in` field but optional parameters are not allowed |
|
|
||||||
|
|
||||||
|
|
||||||
### Input Arguments
|
##### Input section
|
||||||
|
|
||||||
Input arguments defines what data from the HTTP request the method needs. Aicra is able to extract 3 types of data :
|
Input arguments defines what data from the HTTP request the method requires. `aicra` is able to extract 3 types of data :
|
||||||
|
|
||||||
- **URI** - data from inside the request path. For instance, if your controller is bound to the `/user/{id}` URI, you can set the input argument `{id}` matching this uri part.
|
- **URI** - data from inside the request path. For instance, if your controller is bound to the `/user/{id}` URI, you can set the input argument `{id}` matching this uri part.
|
||||||
- **Query** - data formatted at the end of the URL following the standard [HTTP Query](https://tools.ietf.org/html/rfc3986#section-3.4) syntax.
|
- **Query** - data at the end of the URL following the standard [HTTP Query](https://tools.ietf.org/html/rfc3986#section-3.4) syntax.
|
||||||
- **URL encoded** - data send inside the body of the request but following the [HTTP Query](https://tools.ietf.org/html/rfc3986#section-3.4) syntax.
|
- **Form** - data send from the body of the request ; it can be extracted in 3 ways:
|
||||||
- **Multipart** - data send inside the body of the request with a dedicated [format](https://tools.ietf.org/html/rfc2388#section-3). This format is not very lightweight but allows you to receive data as well as files.
|
- _URL encoded_: data send in the body following the [HTTP Query](https://tools.ietf.org/html/rfc3986#section-3.4) syntax.
|
||||||
- **JSON** - data send inside the body as a json object ; each key being a variable name, each value its content. Note that the HTTP header '**Content-Type**' must be set to `application/json` for the API to use it.
|
- _Multipart_: data send in the body with a dedicated [format](https://tools.ietf.org/html/rfc2388#section-3). This format can be quite heavy but allows to transmit data as well as files.
|
||||||
|
- _JSON_: data send in the body as a json object ; each key being a variable name, each value its content. Note that the 'Content-Type' header must be set to `application/json` for the API to use it.
|
||||||
|
|
||||||
|
> For Form data, the 3 methods can be used at once for different arguments; for instance if you need to send a file to an aicra server as well as other parameters, you can use JSON for parameters and Multipart for the file.
|
||||||
|
|
||||||
|
###### Format
|
||||||
|
|
||||||
|
The `in` field describes as list of arguments where the key is the argument name, and the value defines how to manage the variable.
|
||||||
|
|
||||||
|
|
||||||
|
Variable names from **URI** or **Query** must be named accordingly :
|
||||||
|
- an **URI** variable `{var}` from your request route must be named `{var}` in the `in` section
|
||||||
|
- a variable `var` in the **Query** has to be named `GET@var` in the `in` section
|
||||||
|
|
||||||
#### Format
|
|
||||||
|
|
||||||
The `in` field in each method contains as list of arguments where the key is the argument name, and the value defines how to manage the variable.
|
|
||||||
|
|
||||||
> Variable names from **URI** or **Query** must be named accordingly :
|
|
||||||
>
|
|
||||||
> - the **URI** variable `{id}` from your request route must be named `{id}`.
|
|
||||||
> - the variable `somevar` in the **Query** has to be names `GET@somevar`.
|
|
||||||
|
|
||||||
**Example**
|
|
||||||
|
|
||||||
In this example we want 3 arguments :
|
|
||||||
|
|
||||||
|
#### Example
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
"method": "PUT",
|
"method": "PUT",
|
||||||
"path": "/article/{id}",
|
"path": "/article/{id}",
|
||||||
"scope": [["author"]],
|
"scope": [["author"]],
|
||||||
"info": "updates an article",
|
"info": "updates an article",
|
||||||
"in": {
|
"in": {
|
||||||
"{id}": { "info": "article id", "type": "int", "name": "article_id" },
|
"{id}": { "info": "...", "type": "int", "name": "id" },
|
||||||
"GET@title": { "info": "new article title", "type": "?string", "name": "title" },
|
"GET@title": { "info": "...", "type": "?string", "name": "title" },
|
||||||
"content": { "info": "new article content", "type": "string" }
|
"content": { "info": "...", "type": "string" }
|
||||||
},
|
},
|
||||||
"out": {
|
"out": {
|
||||||
"id": { "info": "updated article id", "type": "uint" },
|
"id": { "info": "updated article id", "type": "uint" },
|
||||||
"title": { "info": "updated article title", "type": "string" },
|
"title": { "info": "updated article title", "type": "string" },
|
||||||
"content": { "info": "updated article content", "type": "string" }
|
"content": { "info": "updated article content", "type": "string" }
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
- the 1^st^ one is send at the end of the URI and is a number compliant with the `int` type checker. It is renamed `article_id`, this new name will be sent to the handler.
|
1. `{id}` is extracted from the end of the URI and is a number compliant with the `int` type checker. It is renamed `id`, this new name will be sent to the handler.
|
||||||
- the 2^nd^ one is send in the query (_e.g. [http://host/uri?get-var=value](http://host/uri?get-var=value)_). It must be a valid `string` or not given at all (the `?` at the beginning of the type tells that the argument is **optional**) ; it will be named `title`.
|
2. `GET@title` is extracted from the query (_e.g. [http://host/uri?get-var=value](http://host/uri?get-var=value)_). It must be a valid `string` or not given at all (the `?` at the beginning of the type tells that the argument is **optional**) ; it will be named `title`.
|
||||||
- the 3^rd^ can be send with a **JSON** body, in **multipart** or **URL encoded** it makes no difference and only give clients a choice over the technology to use. If not renamed, the variable will be given to the handler with the name `content`.
|
3. `content` can be extracted from json, multipart or url-encoded data; it makes no difference and only give clients a choice over the technology to use. If not renamed, the variable will be given to the handler with its original name `content`.
|
||||||
|
|
||||||
|
|
||||||
|
# Changelog
|
||||||
|
|
||||||
|
- [x] human-readable json configuration
|
||||||
|
- [x] nested routes (*i.e. `/user/{id}` and `/user/post/{id}`*)
|
||||||
|
- [x] nested URL arguments (*i.e. `/user/{id}` and `/user/{uid}/post/{id}`*)
|
||||||
|
- [x] useful http methods: GET, POST, PUT, DELETE
|
||||||
|
- [ ] add support for PATCH method
|
||||||
|
- [ ] add support for OPTIONS method
|
||||||
|
- [ ] it might be interesting to generate the list of allowed methods from the configuration
|
||||||
|
- [ ] add CORS support
|
||||||
|
- [x] manage request data extraction:
|
||||||
|
- [x] URL slash-separated strings
|
||||||
|
- [x] HTTP Query named parameters
|
||||||
|
- [x] manage array format
|
||||||
|
- [x] body parameters
|
||||||
|
- [x] multipart/form-data (variables and file uploads)
|
||||||
|
- [x] application/x-www-form-urlencoded
|
||||||
|
- [x] application/json
|
||||||
|
- [x] required vs. optional parameters with a default value
|
||||||
|
- [x] parameter renaming
|
||||||
|
- [x] generic type check (*i.e. you can add custom types alongside built-in ones*)
|
||||||
|
- [x] built-in types
|
||||||
|
- [x] `any` - matches any value
|
||||||
|
- [x] `int` - see go types
|
||||||
|
- [x] `uint` - see go types
|
||||||
|
- [x] `float` - see go types
|
||||||
|
- [x] `string` - any text
|
||||||
|
- [x] `string(len)` - any string with a length of exactly `len` characters
|
||||||
|
- [x] `string(min, max)` - any string with a length between `min` and `max`
|
||||||
|
- [ ] `[]a` - array containing **only** elements matching `a` type
|
||||||
|
- [ ] `a[b]` - map containing **only** keys of type `a` and values of type `b` (*a or b can be ommited*)
|
||||||
|
- [x] generic handler implementation
|
||||||
|
- [x] response interface
|
||||||
|
- [x] generic errors that automatically formats into response
|
||||||
|
- [x] builtin errors
|
||||||
|
- [x] possibility to add custom errors
|
||||||
|
- [x] check for missing handlers when building the handler
|
||||||
|
- [x] check handlers not matching a route in the configuration at server boot
|
||||||
|
- [x] specific configuration format errors qt server boot
|
||||||
|
- [x] statically typed handlers - avoids having to check every input and its type (_which is used by context.Context for instance_)
|
||||||
|
- [x] using reflection to use structs as input and output arguments to match the configuration
|
||||||
|
- [x] check for input and output arguments structs at server boot
|
||||||
|
- [x] check for unavailable types in configuration at server boot
|
||||||
|
- [x] recover panics from handlers
|
||||||
|
- [ ] improve tests and coverage
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue