ekwwowhc / golax Goto Github PK

Golax is the official go implementation for the Lax framework.

• About Lax
• Getting started
• Routing example
• Performance
• How interceptor works
• Handling parameters
• Support for Google custom methods
• Sample use cases

Related docs:

• Developer notes
• TODO list

Lax wants to be the best "user experience" for developers making REST APIs.

The design principles for Lax are:

• The lowest language overhead
• Extremely fast to develop
• Very easy to read and trace.

my_api := golax.NewApi()

my_api.Root.
    Interceptor(golax.InterceptorError).
    Interceptor(myLogingInterceptor)

my_api.Root.Node("hello").
    Method("GET", func(c *golax.Context) {
        // At this point, Root interceptors has been already executed
        fmt.Fprintln(c.Response, "Hello world!")
    })

my_api.Serve()

Routing is based on nodes.

There are three types: static, regex and parameter.

• static: Only matches with the url part if it is exactly the same.
• regex: Surrounded by ( and ), if the regex match.
• parameter: Surrounded by { and }, always matches.

The performance compared with the most popular alternative is very similar (actually golax performs slightly better) however code readability and maintainability is far better with golax implementation.

Tests has been executed in a Intel(R) Core(TM) i5-3210M CPU @ 2.50GHz.

Learn more about this https://github.com/fulldump/golax-performance.

If I want to handle a GET /users/1234/stats request, all interceptors in nodes from <root> to .../stats are executed:

To abort the execution, call to c.Error(404, "Resource not found"):

my_api := golax.NewApi()

my_api.Root.
    Node("users").
    Node("{user_id}").
    Method("GET", func (c *golax.Context) {
        fmt.Fprintln(c.Response, "You are looking for user " + c.Parameter)
    })

my_api.Serve()

It is also possible get all parameters:

func (c *golax.Context) {
    fmt.Fprintln(c.Response, "All parameters:", c.Parameters)
}

According to Google's API design guidelines to map RPC services to REST HTTP, it describes custom methods as extra operations that can not be easyly mapped to HTTP verbs. More info about custom methods

For example, this URL has a custom method :activate:

https://my.service.com/v1/users/31231231231:activate

Golax support custom methods as operations:

my_api.Root.
    Node("v1").
    Node("users").
    Node("{user_id}").
    Operation("activate").
    Method("POST", func(c *golax.Context) {
        user_id := c.Parameters["{user_id}"]"
        fmt.Fprintln(c.Response, "Here is custom method ':activate' for user "+user_id)
    })

TODO: put here some examples to cover cool things:

• fluent implementation
• node cycling
• readability
• node preference
• sample logging interceptor
• sample auth interceptor
• sample api errors