From d2e335a57f1c7f59f016cb1b5d3a74f7cd949288 Mon Sep 17 00:00:00 2001 From: xdrm-brackets Date: Wed, 3 Oct 2018 18:37:37 +0200 Subject: [PATCH] doc update --- README.md | 187 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 146 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 38061a2..6881375 100644 --- a/README.md +++ b/README.md @@ -6,30 +6,30 @@ [![Go doc](https://godoc.org/git.xdrm.io/go/aicra?status.svg)](https://godoc.org/git.xdrm.io/go/aicra) -**Aicra** is a self-working **REST API engine** coded in *Go* that allows anyone to create a fully featured 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 compiler (*i.e. aicra*), etc. +**Aicra** is a *configuration-driven* REST **API engine** in *Go* that allows you to create a fully featured API. -All the REST API management is done for you, you just need to implement : +The whole API management is done for you from a configuration file describing your API, you just need to implement : -- the controllers -- the middlewares (to manage authentication, csrf, etc) -- the type checkers to check if input arguments follows some rules +- the controllers +- the middle-wares (_e.g. authentication, csrf_) +- and optionnally the type checkers to check if input values follows some rules -There is 2 drivers that lets you implement these features in Go or whatever language. +> There is 2 available drivers that will load your implementations. The `plugin` driver is for Go programmers, the `generic` one is for any language (it uses standard input and output). -This framework is based over some of the following concepts. +The engine has been designed with the following concepts in mind. | concept | explanation | |---|---| | meaningful defaults | Defaults and default values work without further understanding | -| configuration driven | Avoid information duplication. Automate anything that can be automated without losing control. Have *one* configuration that summarizes the whole project, its behavior and its automation flow. | +| configuration driven | Avoid information duplication. Automate anything that can be automated without losing control. Have *one* configuration that summarizes the whole API, its behavior and its automation flow. | -> A working example is available [here](https://git.xdrm.io/example/aicra) +> A example project is available [here](https://git.xdrm.io/example/aicra) -#### Table of contents +### Table of contents - [I. Installation](#i-installation) @@ -45,7 +45,7 @@ This framework is based over some of the following concepts. -#### I. Installation +### I. Installation You need a recent machine with `go` [installed](https://golang.org/doc/install). @@ -53,72 +53,177 @@ You need a recent machine with `go` [installed](https://golang.org/doc/install). -##### 1. Download and install the package +#### 1. Download and install the package ```bash go get -u git.xdrm.io/go/aicra/cmd/aicra ``` -The library should now be available locally and available for your imports. Moreover, the **project compilet** have been installed as the `aicra` command. +The library should now be available locally as `git.xdrm.io/go/aicra` your imports. Moreover, the **project compiler** have been installed as the `aicra` command. -> 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` for instance. +> 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 symbolic link into `/usr/local/bin` for instance. -#### II. Setup a project +### II. Setup a project -The default project structure for **aicra** is as follows : +The default project structure is : -``` -├── main.go - entry point +```bash +├── main.go # entry point | -├── aicra.json - server configuration file -├── api.json - API configuration file +├── aicra.json # server configuration file +├── api.json # API configuration file | -├── middleware - middleware implementations -├── controller - controller implementations -└── type - custom type checkers +├── middleware # middleware implementations +├── controller # controller implementations +└── type # custom type checkers ``` -##### 1. Compilation configuration +#### 1. Compilation configuration -The `aicra.json` configuration file defines where are located your controllers, type checkers, and middlewares ; also it contains what driver you want to use, you have 2 choices : +The `aicra.json` configuration file defines where are located your controllers, type checkers, and middle-wares ; also it contains what driver you want to use, you have 2 choices : -1. **plugin** - for Go implementations +1. **plugin** - for Go implementations (_c.f. [go plugin system](https://golang.org/pkg/plugin/)_) 2. **generic** - for any language implementation (uses standard input and output) -| field | description | example value | -| ------------------ | ------------------------------------------------------------ | -------------------- | -| root | The project folder path | `./some-path` | -| driver | The driver to use for loading controllers, middlewares and type checkers | `plugin` or`generic` | -| types.default | Whether to load default types into the project | `true`, `false` | -| types.folder | The folder (relative to the project root) where type checkers' implementations are located | `./type` | -| controllers.folder | The folder (relative to the project root) where controllers' implementations are located | `./controller` | -| middlewares.folder | The folder (relative to the project root) where middlewares' implementations are located | `./middleware` | + + +The file uses the [json](https://json.org/) format, each field is described in the table above. + +| field | description | example value | +| ---------------------- | ------------------------------------------------------------ | --------------------------------- | +| `root` | The project folder path | `./some-path` or `/some/path` | +| `driver` | The driver to use for loading controllers, middlewares and type checkers | `plugin` or `generic` | +| `types`.`default` | Whether to load default types into the project | `true` or `false` | +| `types`.`folder` | The folder (relative to the project root) where type checkers' implementations are located | `./type` or `type` | +| `controllers`.`folder` | The folder (relative to the project root) where controllers' implementations are located | `./controller` or `controller` | +| `middlewares`.`folder` | The folder (relative to the project root) where middlewares' implementations are located | `./middleware` or `middleware` | A sample file can be found [here](https://git.xdrm.io/example/aicra/src/master/aicra.json). -##### 2. API Configuration +###### Example + +In this example we have the controllers inside the `controller` folder, the middle-wares in the `middleware` folder and custom type checkers inside the `checker` folder, we want to load the built-in type checkers and are using the `plugin` driver. Also our project root is the relative current path `.` ; note that it is better using an absolute path as your project root. + +```json +{ + "root": ".", + "driver": "plugin", + "types": { + "default": true, + "folder": "type" + }, + "controllers": { + "folder": "controller.plugin" + }, + "middlewares": { + "folder": "middleware.plugin" + } +} +``` + + + +#### 2. API Configuration The whole project behavior is described inside the `api.json` file. For a better understanding of the format, take a look at this working [template](https://git.xdrm.io/example/aicra/src/master/api.json). This file defines : - resource routes and their methods - every input for each method (called *argument*) - every output for each method -- scope permissions (list of permissions you can compose) +- scope permissions (list of permissions needed for clients to use which method) - input policy : - - type of argument + - type of argument (_i.e. for type checkers_) - required/optional - default value - variable renaming +###### Definition + +At the root of the json file are available 5 field names : + +1. `GET` - to define what to do when receiving a request with a GET HTTP method at the root URI +2. `POST` - to define what to do when receiving a request with a POST HTTP method at the root URI +3. `PUT` - to define what to do when receiving a request with a PUT HTTP method at the root URI +4. `DELETE` - to define what to do when receiving a request with a DELETE HTTP method at the root URI +5. `/` - to define children URIs ; each will have the same available fields -##### 3. Controllers + +For each method you will have to create fields described in the table above. + +| field path | description | example | +| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| `info` | A short human-readable description of what the method does | `create a new user` | +| `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) | +| `in` | The list of arguments that the clients will have to provide. See [here](#input-arguments) for details. | | +| `out` | The list of output data that will be returned by your controllers. It has the same syntax as the `in` field but is only use for readability purpose and documentation. | | + + + +##### Input Arguments + +###### 1. Input types + +Input arguments defines what data from the HTTP request the method needs. Aicra is able to extract 3 types of data : + +- **URI** - Slash-separated strings right after the resource URI. For instance, if your controller is bound to the `/user` URI, you can use the *URI slot* right after to send the user ID ; Now a client can send requests to the URI `/user/:id` where `:id` is a number sent by the client. This kind of input cannot be extracted by name, but rather by index in the URL (_begins at 0_). +- **Query** - data formatted 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. +- **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. +- **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. + + + +###### 2. Global 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 must be prefixed when requesting **URI** or **Query** input types. +> +> - The first **URI** data has to be named `URL#0`, the second one `URL#1` and so on... +> - The variable named `somevar` in the **Query** has to be named `GET@somvar` in the configuration. + +**Example** + +In this example we want 3 arguments : + +- the 1^st^ one is send at the end of the URI and is a number compliant with the `int` type checker (else the controller will not be run). It is renamed `uri-param`, this new name will be sent to the controller. +- 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 `int` or not given at all (the `?` at the beginning of the type tells that the argument is **optional**) ; it will be named `get-param`. +- 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 controller with the name `multipart-var`. + +```json +"in": { + // arg 1 + "URL#0": { + "info": "some integer in the URI", + "type": "int", + "name": "uri-param" + }, + // arg 2 + "GET@get-var": { + "info": "some Query OPTIONAL variable", + "type": "?int", + "name": "get-param" + }, + "multipart-var": { /* ... */ } +} +``` + + + +###### Example + +In this example you can see a pretty basic user/article REST API definition. The API let's you fetch, create, edit, and delete users and do the same for their articles. Users actions will be available at the uri `/user`, and `/article` for articles. + + + +#### 3. Controllers Controllers implement `Get`, `Post`, `Put`, and `Delete` methods, and have access to special variables surrounded by underscores : @@ -162,7 +267,7 @@ A sample directory structure is available [here](https://git.xdrm.io/example/aic -##### 4. Middlewares +#### 4. Middlewares In order for your project to manage authentication, the best solution is to create middlewares, there are programs that updates a *Scope* (*i.e. a list of strings*) according to internal or persistent (*i.e.* database) information and the actual http request. They are all run before each request is forwarded to your controller. The scope are used to match the `scope` field in the configuration file and automatically block non-authenticated requests. Scopes can also be used for implementation-specific behavior such as _CSRF_ management. Controllers have access to the scope through the variable `_SCOPE_`. @@ -194,7 +299,7 @@ A sample directory structure is available [here](https://git.xdrm.io/example/aic -##### 5. Custom types +#### 5. Type checkers 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/internal/checker/default). Also it is not required that you use built-in types, you can ignore them by setting `types.default = false` in the _aicra.json_ configuration. @@ -218,7 +323,7 @@ A sample directory structure is available [here](https://git.xdrm.io/example/aic -#### III. Build your project +### III. Build your project After each controller, middleware or type implementation, you'll have to compile the project. This can be achieved through the command-line builder.