🚀 Fast, intuitive, and powerful configuration-driven engine for faster and easier REST development
Go to file
Adrien Marquès ee72e2d285 move .build/types to .build/type + update checker accordingly 2018-07-07 18:05:57 +02:00
checker move .build/types to .build/type + update checker accordingly 2018-07-07 18:05:57 +02:00
clifmt build controller + types is ok 2018-07-07 16:35:20 +02:00
cmd/aicra move .build/types to .build/type + update checker accordingly 2018-07-07 18:05:57 +02:00
config new configuration format (more explicit + cleaner) 2018-06-03 15:08:47 +02:00
err moved 'err' into package 2018-06-01 09:09:32 +02:00
implement rename repo 2018-07-05 19:15:57 +02:00
multipart removed from /internal directory 2018-05-30 09:02:08 +02:00
request rename repo 2018-07-05 19:15:57 +02:00
.gitignore rename type build script + add controller build script + update 'readme' to _checkable_ changelog 2018-05-31 09:23:06 +02:00
LICENSE first commit 2018-05-19 12:04:45 +02:00
README.md remove old builders (bash) + update readme 2018-07-07 17:40:59 +02:00
server.go move .build/types to .build/type + update checker accordingly 2018-07-07 18:05:57 +02:00
types.go rename repo 2018-07-05 19:15:57 +02:00
util.go refactor 'router' + 'loader' into 'server' 2018-07-06 10:49:52 +02:00

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

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 values
    • int - any number (e.g. float, int, uint)
    • string - any text
    • varchar(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)
  • generic controllers implementation (shared objects)
  • response interface