Comment on page
Path Parameter Types
Iris provides the easiest and the most powerful routing process you have ever experienced.
Iris has its own interpreter for route’s path syntax, which can parse and evaluate complex expressions (yes, like a programming language!).
It’s fast, because it optimizes its routing based on the needs of each route. If no special regexp is needed, it registers the route with the low-level path syntax. If regexp is needed, it pre-compiles it and adds the necessary middleware(s). That means that you have zero performance cost compared to other routers or web frameworks.
A path parameter's name should contain only alphabetical letters. Numbers or symbols like '_' are NOT allowed.
Do not confuse
ctx.Params() with ctx.Values().- Path parameter's values can be retrieved from
ctx.Params(). - Context's local storage that can be used to communicate between handlers and middleware(s) can be stored to
ctx.Values().
The built-in available parameter types can be found at the following table.
Param Type | Go Type | Validation | Retrieve Helper |
|---|---|---|---|
:string | string | anything (single path segment) | Params().Get |
:uuid | string | uuidv4 or v1 (single path segment) | Params().Get |
:int | int | -9223372036854775808 to 9223372036854775807 (x64) or -2147483648 to 2147483647 (x32), depends on the host arch | Params().GetInt |
:int8 | int8 | -128 to 127 | Params().GetInt8 |
:int16 | int16 | -32768 to 32767 | Params().GetInt16 |
:int32 | int32 | -2147483648 to 2147483647 | Params().GetInt32 |
:int64 | int64 | -9223372036854775808 to 9223372036854775807 | Params().GetInt64 |
:uint | uint | 0 to 18446744073709551615 (x64) or 0 to 4294967295 (x32), depends on the host arch | Params().GetUint |
:uint8 | uint8 | 0 to 255 | Params().GetUint8 |
:uint16 | uint16 | 0 to 65535 | Params().GetUint16 |
:uint32 | uint32 | 0 to 4294967295 | Params().GetUint32 |
:uint64 | uint64 | 0 to 18446744073709551615 | Params().GetUint64 |
:bool | bool | "1" or "t" or "T" or "TRUE" or "true" or "True" or "0" or "f" or "F" or "FALSE" or "false" or "False" | Params().GetBool |
:alphabetical | string | lowercase or uppercase letters | Params().Get |
:file | string | lowercase or uppercase letters, numbers, underscore (_), dash (-), point (.) and no spaces or other special characters that are not valid for filenames | Params().Get |
:path | string | anything, can be separated by slashes (path segments) but should be the last part of the route path | Params().Get |
:uuid | string | uuidv4 (and v1) path parameter validation | Params().Get |
:mail | string | email without domain validation | Params().Get |
:email | string | email with domain validation | Params().Get |
:date | string | yyyy/mm/dd format e.g. /blog/{param:date} matches /blog/2022/04/21 | `Params().SimpleDate( |
:weekday | uint or string | 0-6 positive integer or longname format ("sunday" to "monday" or "Sunday" to "Monday") | Params().GetWeekday |
Usage:
app.Get("/users/{id:uint64}", func(ctx iris.Context){
id := ctx.Params().GetUint64Default("id", 0)
// [...]
})
Built-in Func | Param Types |
|---|---|
regexp(expr string) | :string |
prefix(prefix string) | :string |
suffix(suffix string) | :string |
contains(s string) | :string |
min(minValue int or int8 or int16 or int32 or int64 or uint8 or uint16 or uint32 or uint64 or float32 or float64) | :string(char length), :int, :int8, :int16, :int32, :int64, :uint, :uint8, :uint16, :uint32, :uint64 |
max(maxValue int or int8 or int16 or int32 or int64 or uint8 or uint16 or uint32 or uint64 or float32 or float64) | :string(char length), :int, :int8, :int16, :int32, :int64, :uint, :uint8, :uint16, :uint32, :uint64 |
range(minValue, maxValue int or int8 or int16 or int32 or int64 or uint8 or uint16 or uint32 or uint64 or float32 or float64) | :int, :int8, :int16, :int32, :int64, :uint, :uint8, :uint16, :uint32, :uint64 |
Usage:
app.Get("/profile/{name:alphabetical max(255)}", func(ctx iris.Context){
name := ctx.Params().Get("name")
// len(name) <=255 otherwise this route will fire 404 Not Found
// and this handler will not be executed at all.
})
Do It Yourself:
The
RegisterFunc can accept any function that returns a func(paramValue string) bool. Or just a func(string) bool. If the validation fails then it will fire 404 or whatever status code the else keyword has.latLonExpr := "^-?[0-9]{1,3}(?:\\.[0-9]{1,10})?$"
latLonRegex, _ := regexp.Compile(latLonExpr)
// Register your custom argument-less macro function to the :string param type.
// MatchString is a type of func(string) bool, so we use it as it is.
app.Macros().Get("string").RegisterFunc("coordinate", latLonRegex.MatchString)
app.Get("/coordinates/{lat:string coordinate()}/{lon:string coordinate()}",
func(ctx iris.Context) {
ctx.Writef("Lat: %s | Lon: %s", ctx.Params().Get("lat"), ctx.Params().Get("lon"))
})
Register your custom macro function which accepts two int arguments.
app.Macros().Get("string").RegisterFunc("range",
func(minLength, maxLength int) func(string) bool {
return func(paramValue string) bool {
return len(paramValue) >= minLength && len(paramValue) <= maxLength
}
})
app.Get("/limitchar/{name:string range(1,200) else 400}", func(ctx iris.Context) {
name := ctx.Params().Get("name")
ctx.Writef(`Hello %s | the name should be between 1 and 200 characters length
otherwise this handler will not be executed`, name)
})
Register your custom macro function which accepts a slice of strings
[...,...].app.Macros().Get("string").RegisterFunc("has",
func(validNames []string) func(string) bool {
return func(paramValue string) bool {
for _, validName := range validNames {
if validName == paramValue {
return true
}
}
return false
}
})
app.Get("/static_validation/{name:string has([kataras,maropoulos])}",
func(ctx iris.Context) {
name := ctx.Params().Get("name")
ctx.Writef(`Hello %s | the name should be "kataras" or "maropoulos"
otherwise this handler will not be executed`, name)
})
Example Code:
func main() {
app := iris.Default()
// This handler will match /user/john 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 handler will match /users/42
// but will not match /users/-1 because uint should be bigger than zero
// neither /users or /users/.
app.Get("/users/{id:uint64}", func(ctx iris.Context) {
id := ctx.Params().GetUint64Default("id", 0)
ctx.Writef("User with ID: %d", id)
})
// However, this one will match /user/john/send and also /user/john/everything/else/here
// but will not match /user/john neither /user/john/.
app.Post("/user/{name:string}/{action:path}", func(ctx iris.Context) {
name := ctx.Params().Get("name")
action := ctx.Params().Get("action")
message := name + " is " + action
ctx.WriteString(message)
})
app.Listen(":8080")
}
When parameter type is missing then it defaults to thestringone, therefore{name:string}and{name}refers to the same exactly thing.
Last modified 4mo ago