Languages

English | 简体中文

For old versions

Kite framework is not stable yet, features may be added or modified in future releases, if you're trying sketch project with the framework behind and confronting some errors, for example, everthing works perfectly on one machine but failed after project is moved to another machine, please specify a version in package.json like this ( reinstall dependencies npm install required ):

{
  "dependencies": {
    "kite-framework": "=0.5.5"
  }
}

KiteJS framework

A Simple, clear web API framework.

Please visit Kite Examples for more examples.

We also provided Kite CLI tools:

npm install -g kite-tools

If you're using Linux and MacOS systems, you suppose to run

sudo npm install -g kite-tools

With "kite-tools" you can easily create Kite projects and write APIs. The following examples are demostrated with "kite-tools", if you wonder more about creating Kite projects with bare hands, please see Kite project step by step.

Installation

Before you start, please make sure you have:

• NodeJs, version >= 8.0.0
• TypeScript, verstion >= 2.4
• TypeScript IDE, Visual Studio Code is recommended here

Once you've installed Kite CLI tools, type this command in terminal to create a Kite project:

kite -p --yes first-kite-app

Explanation for the upper command:

• kite : Kite CLI tools command name
• -p option : create and initialize a Kite project
• --yes option : create without questioning, use default configuration
• first-kite-app option: application name, here we use "first-kite-app"

Then Kite CLI tools will create a folder first-kite-app, initialize the project folder with some files and directories, install NodeJS dependencies as well.

Making Kite fly

If the above steps finished without error, now you can enter the project folder, and start Kite application server:

cd first-kite-app
npm start

After a few seconds waiting for TypeScript compilation / NodeJS running, you'll see a message like:

2018-3-23 10:13:24 [ KITE  ] Flying! server listening at 127.0.0.1:4000

which means Kite application server is successfully started, then open a browser window and visit 127.0.0.1:4000 (or localhost:4000), you will get a message like:

{"error":{"code":1002,"msg":"Resource not found"}}

don't worry about this error message, it's just means the request resource / was not found on server, your application just works great.

First API

Using kite-tools, you can easily create Kite APIs. Open a new terminal (keep previous terminal running, which servicing your application), under project folder type this command:

kite -a greet

Kite CLI tools will generate a file named greet.controller.ts under src/controllers/ folder, it looks like this:

import { Controller, Entry, KiteError, Inject } from 'kite-framework';

@Controller()
export class GreetController {
    @Entry()
    async exec() {
        throw new KiteError(1000, 'this api is not implemented');
    }
}

then run command tsc to compile this TypeScript source:

tsc

Now you can try this API by visiting http://localhost:4000/greet, here is the response:

{"error":{"code":1000,"msg":"this api is not implemented"}}

Hello world! (plain text output)

Simply returns a string from APIs will cause the framework outputs content in text/plain type. API source greet.controller.ts example:

import { Controller, Entry, KiteError, Inject } from 'kite-framework';

@Controller()
export class GreetController {
    @Entry()
    async exec() {
        return "hello world!";
    }
}

Save and run tsc to compile ( boring with typing tsc everytime? open a new terminal and try tsc -w, see TypeScript compiler watch mode ).

Now refresh the page(http://localhost:4000/greet), response:

hello world!

Hello world! (json output)

KiteJS is a framework focusing on web APIs, an API is generally output a JSON formatted string, and in JavaScript/NodeJs, why not JSON?

Returns an object from APIs will cause the framework outputs content in application/json type. API source greet.controller.ts example:

import { Controller, Entry, KiteError, Inject } from 'kite-framework';

@Controller()
export class GreetController {
    @Entry()
    async exec() {
        return { msg: "hello world!" };
    }
}

Compile the source (if not running tsc -w) and refresh the page, response like:

{"msg":"hello world!"}

Accepting client parameters

Declared arguments in Kite entry point function (exec() as of yet) is mapped to client parameters by KiteJS framework at controller loading time.

Here is an example (create a new controller welcome.controller.ts by kite-tools kite -a welcome):

import { Controller, Entry, KiteError, Inject } from 'kite-framework';

@Controller()
export class WelcomeController {
    @Entry()
    async exec(name: string) {
        return { msg: `Hello, ${name}!` };
    }
}

Compile the source (if not running tsc -w), and visit http://localhost:4000/welcome?name=Kite, response like:

{"msg":"Hello, Kite!"}

Note

Variable type declaration is strongly recommended in KiteJS, this improves coding efficiency, and also saves the time of dynamical loading stage of the framework. If you ommitted type declaration from parameter, it'll be treated as "string" defaultly.

Why KiteJS? What's the differences between ExpressJS / KoaJS

KiteJS is designed for easier / faster writing web APIs that using new ECMA features, like decorator, async, await, reflection etc. It's writen from TypeScript, and TypeScript is suggested for writing Kite APIs.

With TypeScript, Kite implemented another important feature - schema checking - yes, the missing MogonDB schema is here! See ...

With TypeScript, something is awsome in KiteJS:

• input data type conversion - Kite automatically convert input data from string (or any other types) to declared types
• input data mapping - Kite can easily map input data to custom objects or contoller arguments
• input data validation - by defining some rules, Kite checks the input data for you
• modularization APIs - one API one file, easy group working, easy code maintainance