Path Parameter Types
Iris has the easiest and the most powerful routing process you have ever met.
Iris has its own interpeter for route's path syntax, parsing and evaluation (yes, like a programming language!).
It's fast, how? It calculates its needs and if not any special regexp needed then it just registers the route with the low-level path syntax, otherwise it pre-compiles the regexp and adds the necessary middleware(s). That means that you have zero performance cost compared to other routers or web frameworks.

Parameters

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
Usage:
1
app.Get("/users/{id:uint64}", func(ctx iris.Context){
2
id := ctx.Params().GetUint64Default("id", 0)
3
// [...]
4
})
Copied!
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:
1
app.Get("/profile/{name:alphabetical max(255)}", func(ctx iris.Context){
2
name := ctx.Params().Get("name")
3
// len(name) <=255 otherwise this route will fire 404 Not Found
4
// and this handler will not be executed at all.
5
})
Copied!
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.
1
latLonExpr := "^-?[0-9]{1,3}(?:\\.[0-9]{1,10})?quot;
2
latLonRegex, _ := regexp.Compile(latLonExpr)
3
4
// Register your custom argument-less macro function to the :string param type.
5
// MatchString is a type of func(string) bool, so we use it as it is.
6
app.Macros().Get("string").RegisterFunc("coordinate", latLonRegex.MatchString)
7
8
app.Get("/coordinates/{lat:string coordinate()}/{lon:string coordinate()}",
9
func(ctx iris.Context) {
10
ctx.Writef("Lat: %s | Lon: %s", ctx.Params().Get("lat"), ctx.Params().Get("lon"))
11
})
Copied!
Register your custom macro function which accepts two int arguments.
1
app.Macros().Get("string").RegisterFunc("range",
2
func(minLength, maxLength int) func(string) bool {
3
return func(paramValue string) bool {
4
return len(paramValue) >= minLength && len(paramValue) <= maxLength
5
}
6
})
7
8
app.Get("/limitchar/{name:string range(1,200) else 400}", func(ctx iris.Context) {
9
name := ctx.Params().Get("name")
10
ctx.Writef(`Hello %s | the name should be between 1 and 200 characters length
11
otherwise this handler will not be executed`, name)
12
})
Copied!
Register your custom macro function which accepts a slice of strings [...,...].
1
app.Macros().Get("string").RegisterFunc("has",
2
func(validNames []string) func(string) bool {
3
return func(paramValue string) bool {
4
for _, validName := range validNames {
5
if validName == paramValue {
6
return true
7
}
8
}
9
10
return false
11
}
12
})
13
14
app.Get("/static_validation/{name:string has([kataras,maropoulos])}",
15
func(ctx iris.Context) {
16
name := ctx.Params().Get("name")
17
ctx.Writef(`Hello %s | the name should be "kataras" or "maropoulos"
18
otherwise this handler will not be executed`, name)
19
})
Copied!
Example Code:
1
func main() {
2
app := iris.Default()
3
4
// This handler will match /user/john but will not match neither /user/ or /user.
5
app.Get("/user/{name}", func(ctx iris.Context) {
6
name := ctx.Params().Get("name")
7
ctx.Writef("Hello %s", name)
8
})
9
10
// This handler will match /users/42
11
// but will not match /users/-1 because uint should be bigger than zero
12
// neither /users or /users/.
13
app.Get("/users/{id:uint64}", func(ctx iris.Context) {
14
id := ctx.Params().GetUint64Default("id", 0)
15
ctx.Writef("User with ID: %d", id)
16
})
17
18
// However, this one will match /user/john/send and also /user/john/everything/else/here
19
// but will not match /user/john neither /user/john/.
20
app.Post("/user/{name:string}/{action:path}", func(ctx iris.Context) {
21
name := ctx.Params().Get("name")
22
action := ctx.Params().Get("action")
23
message := name + " is " + action
24
ctx.WriteString(message)
25
})
26
27
app.Listen(":8080")
28
}
Copied!
When parameter type is missing then it defaults to the string one, therefore {name:string} and {name} refers to the same exactly thing.
Last modified 2mo ago
Export as PDF
Copy link
Contents
Parameters