API Route Rules

Overview

In go-zero, HTTP services are declared in the api language and then generated by goctl. For the complete api language reference, see the API DSL overview.

The api language has specific routing rules that differ slightly from standard HTTP routing conventions.

Route Rules

In api description, routing needs to meet the following rules

1. Route must start with /
2. Route node must be separated by /
3. A route node may contain :, but : must be the first character of the node. The corresponding request body field must carry a path tag to receive the path parameter — see parameter rules for details.
4. Route nodes may contain letters, numbers (requires goctl 1.5.1+, see new API feature guide), underscores, and dashes.

Route Example：

syntax = "v1"

type DemoPath3Req {
    Id int64 `path:"id"`
}

type DemoPath4Req {
    Id   int64  `path:"id"`
    Name string `path:"name"`
}

type DemoPath5Req {
    Id   int64  `path:"id"`
    Name string `path:"name"`
    Age  int    `path:"age"`
}

type DemoReq {}

type DemoResp {}

service Demo {
    // route example /foo
    @handler demoPath1
    get /foo (DemoReq) returns (DemoResp)

    // route example /foo/bar
    @handler demoPath2
    get /foo/bar (DemoReq) returns (DemoResp)

    // route example /foo/bar/:id，where id is a field in the request body
    @handler demoPath3
    get /foo/bar/:id (DemoPath3Req) returns (DemoResp)

    // route example /foo/bar/:id/:name，where id and name are fields in the request body
    @handler demoPath4
    get /foo/bar/:id/:name (DemoPath4Req) returns (DemoResp)

    // route example /foo/bar/:id/:name/:age，where id, name, age are the fields in the request body
    @handler demoPath5
    get /foo/bar/:id/:name/:age (DemoPath5Req) returns (DemoResp)

    // route example /foo/bar/baz-qux
    @handler demoPath6
    get /foo/bar/baz-qux (DemoReq) returns (DemoResp)

    // route example/foo/bar_baz/123(support version after goctl 1.5.1)
    @handler demoPath7
    get /foo/bar_baz/123 (DemoReq) returns (DemoResp)
}