Iris Web Framework

Iris is a fast, simple yet fully featured and very efficient web framework for Go.

Iris provides a beautifully expressive and easy to use foundation for your next website or API.

Finally, a real expressjs equivalent for the Go Programming Language.

Learn what others say about Iris and star this github repository to stay up to date.

Installation

The only requirement is the Go Programming Language

$ go get -u github.com/kataras/iris

Iris takes advantage of the vendor directory feature. You get truly reproducible builds, as this method guards against upstream renames and deletes.

Updated at: Tuesday, 21 November 2017

Benchmarks from third-party source over the rest web frameworks

Known issues for code editors and IDEs at general

VS Code

For some reason the latest vscode-go language extension does not provide enough intelligence for the iris.Context type alias (input parameters documentation and definition navigation). Probably you have already experienced this issue with other Go libraries too, it is not an iris-specific issue, it is a general issue for all Golang type aliases.

Therefore if you use VS Code and you need these editor's features, import the original path; add an extra import statement of the original path of the Context, that will do it:

import (
    "github.com/kataras/iris"
    "github.com/kataras/iris/context" // <- HERE
)

Philosophy

The Iris philosophy is to provide robust tooling for HTTP, making it a great solution for single page applications, web sites, hybrids, or public HTTP APIs. Keep note that, so far, iris is the fastest web framework ever created in terms of performance.

Iris does not force you to use any specific ORM or template engine. With support for the most used template engines, you can quickly craft the perfect application.

Quick start

$ cat example.go

package main

import "github.com/kataras/iris"

func main() {
    app := iris.Default()
    app.Get("/ping", func(ctx iris.Context) {
        ctx.JSON(iris.Map{
            "message": "pong",
        })
    })

    // Listen and serve on http://localhost:8080.
    app.Run(iris.Addr(":8080"))
}

$ go run example.go
Now listening on: http://localhost:8080
Application Started. Press CTRL+C to shut down.
_

Using Get, Post, Put, Patch, Delete and Options

func main() {
    // Creates an application with default middleware:
    // logger and recovery (crash-free) middleware.
    app := iris.Default()

    app.Get("/someGet", getting)
    app.Post("/somePost", posting)
    app.Put("/somePut", putting)
    app.Delete("/someDelete", deleting)
    app.Patch("/somePatch", patching)
    app.Head("/someHead", head)
    app.Options("/someOptions", options)

    app.Run(iris.Addr(":8080"))
}

Parameters in path

func main() {
    app := iris.Default()

    // This handler will match /user/kataras but will not match neither /user/ or /user.
    app.Get("/user/{name}", func(ctx iris.Context) {
        name := ctx.Params().Get("name")
        ctx.Writef("Hello %s", name)
    })

    // This handles the /user/kataras/42
    // and fires 400 bad request if /user/kataras/string.
    // The "else 400" is optionally:
    // by-default it will fire 404 not found if alphanumeric instead
    // of number passed on the "age" parameter.
    app.Get("/user/{name:string}/{age:int else 400}", func(ctx iris.Context) {
        name := ctx.Params().Get("name")
        age, _ := ctx.Params().GetInt("age")
        ctx.Writef("%s is %d years old", name, age)
    })

    // However, this one will match /action/{user}/star and also /action/{user}/stars
    // or even /action/{user}/likes/page/2.
    // It should match anything after the /action/{user}/
    // except the /action/{user}/static which is handled by the below route.
    app.Get("/action/{user:string}/{action:path}", func(ctx iris.Context) {
        user := ctx.Params().Get("user")
        action := ctx.Params().Get("action")
        ctx.Writef("user: %s | action: %s", user, action)
    })

    // Unlike other frameworks and routers,
    // Iris is smart enough to understand that this is not the previous,
    // wildcard of type path route, it should only match the /action/{user}/static.
    app.Get("/action/{user:string}/static", func(ctx iris.Context) {
        user := ctx.Params().Get("user")
        ctx.Writef("static path for user: %s", user)
    })


    // http://localhost:8080/user/kataras
    // http://localhost:8080/user/kataras/25
    // http://localhost:8080/action/kataras/upgrade
    // http://localhost:8080/action/kataras/static
    app.Run(iris.Addr(":8080"))
}

If parameter type is missing then defaults to string, therefore {name:string} and {name} do the same exactly thing.

Learn more about path parameter's types by navigating here.

Cookies

$ cat _examples/cookies/basic/main.go

package main

import "github.com/kataras/iris"

func newApp() *iris.Application {
    app := iris.New()

    // Set A Cookie.
    app.Get("/cookies/{name}/{value}", func(ctx iris.Context) {
        name := ctx.Params().Get("name")
        value := ctx.Params().Get("value")

        ctx.SetCookieKV(name, value)

        ctx.Writef("cookie added: %s = %s", name, value)
    })

    // Retrieve A Cookie.
    app.Get("/cookies/{name}", func(ctx iris.Context) {
        name := ctx.Params().Get("name")

        value := ctx.GetCookie(name)

        ctx.WriteString(value)
    })

    // Delete A Cookie.
    app.Delete("/cookies/{name}", func(ctx iris.Context) {
        name := ctx.Params().Get("name")

        ctx.RemoveCookie(name)

        ctx.Writef("cookie %s removed", name)
    })

    return app
}

func main() {
    app := newApp()

    // GET:    http://localhost:8080/cookies/my_name/my_value
    // GET:    http://localhost:8080/cookies/my_name
    // DELETE: http://localhost:8080/cookies/my_name
    app.Run(iris.Addr(":8080"))
}

• Alternatively, use a regular http.Cookie: ctx.SetCookie(&http.Cookie{...})
• If you want to set custom the path: ctx.SetCookieKV(name, value, iris.CookiePath("/custom/path/cookie/will/be/stored")).
• If you want to be available only to the current request path: ctx.SetCookieKV(name, value, iris.CookieCleanPath /* or iris.CookiePath("") */)
  • iris.CookieExpires(time.Duration)
  • iris.CookieHTTPOnly(false)
• ctx.Request().Cookie(name) is also available, it's the net/http approach
• Learn more about path parameter's types by clicking here.

Testing

package main

import (
    "fmt"
    "testing"

    "github.com/kataras/iris/httptest"
)

// go test -v -run=TestCookiesBasic$
func TestCookiesBasic(t *testing.T) {
    app := newApp()
    e := httptest.New(t, app, httptest.URL("http://example.com"))

    cookieName, cookieValue := "my_cookie_name", "my_cookie_value"

    // Test Set A Cookie.
    t1 := e.GET(fmt.Sprintf("/cookies/%s/%s", cookieName, cookieValue)).Expect().Status(httptest.StatusOK)
    t1.Cookie(cookieName).Value().Equal(cookieValue) // validate cookie's existence, it should be there now.
    t1.Body().Contains(cookieValue)

    path := fmt.Sprintf("/cookies/%s", cookieName)

    // Test Retrieve A Cookie.
    t2 := e.GET(path).Expect().Status(httptest.StatusOK)
    t2.Body().Equal(cookieValue)

    // Test Remove A Cookie.
    t3 := e.DELETE(path).Expect().Status(httptest.StatusOK)
    t3.Body().Contains(cookieName)

    t4 := e.GET(path).Expect().Status(httptest.StatusOK)
    t4.Cookies().Empty()
    t4.Body().Empty()
}

Learn

First of all, the most correct way to begin with a web framework is to learn the basics of the programming language and the standard http capabilities, if your web application is a very simple personal project without performance and maintainability requirements you may want to proceed just with the standard packages. After that follow the guidelines:

• Navigate through 100+1 examples and some iris starter kits we crafted for you
• Read the godocs for any details
• Prepare a cup of coffee or tea, whatever pleases you the most, and read some articles we found for you

Iris starter kits

1. A basic web app built in Iris for Go
2. A mini social-network created with the awesome Iris💖💖
3. Iris isomorphic react/hot reloadable/redux/css-modules starter kit
4. Demo project with react using typescript and Iris
5. Self-hosted Localization Management Platform built with Iris and Angular
6. Iris + Docker and Kubernetes
7. Quickstart for Iris with Nanobox
8. A Hasura starter project with a ready to deploy Golang hello-world web app with IRIS

Did you build something similar? Let us know!

Middleware

Iris has a great collection of handlers[1][2] that you can use side by side with your web apps. However you are not limited to them - you are free to use any third-party middleware that is compatible with the net/http package, _examples/convert-handlers will show you the way.

Iris, unlike others, is 100% compatible with the standards and that's why the majority of the big companies that adapt Go to their workflow, like a very famous US Television Network, trust Iris; it's up-to-date and it will be always aligned with the std net/http package which is modernized by the Go Authors on each new release of the Go Programming Language.

Articles

• A Todo MVC Application using Iris and Vue.js
• A Hasura starter project with a ready to deploy Golang hello-world web app with IRIS
• Top 6 web frameworks for Go as of 2017
• Iris Go Framework + MongoDB
• How to build a file upload form using DropzoneJS and Go
• How to display existing files on server using DropzoneJS and Go
• Iris, a modular web framework
• Go vs .NET Core in terms of HTTP performance
• Iris Go vs .NET Core Kestrel in terms of HTTP performance
• How to Turn an Android Device into a Web Server
• Deploying a Iris Golang app in hasura
• A URL Shortener Service using Go, Iris and Bolt

Video Courses

Name	Producer
Daily Coding - Web Framework Golang: Iris Framework	WarnabiruTV
Playlist: Tutorial Golang MVC Iris Framework	Musobar Media
Go/Golang 27 - Iris framework : Routage de base	stephgdesign
Go/Golang 28 - Iris framework : Templating	stephgdesign
Go/Golang 29 - Iris framework : Paramètres	stephgdesign
Go/Golang 30 - Iris framework : Les middelwares	stephgdesign
Go/Golang 31 - Iris framework : Les sessions	stephgdesign

Support

• HISTORY file is your best friend, it contains information about the latest features and changes
• Did you happen to find a bug? Post it at github issues
• Do you have any questions or need to speak with someone experienced to solve a problem at real-time? Join us to the community chat
• Complete our form-based user experience report by clicking here
• Do you like the framework? Tweet something about it! The People have spoken:

For more information about contributing to the Iris project please check the CONTRIBUTING.md file.

List of all Contributors

Get hired

There are many companies and start-ups looking for Go web developers with Iris experience as requirement, we are searching for you every day and we post those information via our facebook page, like the page to get notified, we have already posted some of them.

Backers

Thank you to all our backers! 🙏 Become a backer

License

Iris is licensed under the 3-Clause BSD License. Iris is 100% free and open-source software.

For any questions regarding the license please send e-mail.