Home

A possible way (just a thought for now) of registering a service and how the discovery doc would be inferred from it:

type Req struct {
    A int     `endpoints:"path"`                   // implies "required"
    B float64 `endpoints:"required"`               // does not imply "path"
    C bool                                         // default location is "query"
    D string  `endpoints:"{hello|goodbye},path"`   // regexp "pattern"
}

type MyService struct {}

// DoSomething is free to return any kind of value that implements the error interface.
// Some values of Error() have a special meaning and will result in a specific
// HTTP status code as a response to the client:
// "Bad Request" => 400
// "Unauthorized" => 401
// "Forbidden" => 403
// "Not Found" => 404
// "Internal Server Error" => 500
//
// If the method wants to return a non-default error message, it can do so in a suffix, e.g.
// "Not Found: Look somewhere else!"
//
// When returned error doesn't match any of the above, the default HTTP status code is 500.
func (s *MyService) DoSomething(req *Req, resp *Resp) error {
    // ...
}

func init() {
    s := new(MyService)

    // Will implicitly call
    // endpoints.RegisterService(s, "myservice", "v1", "My Service API", "description")
    // then register methods of s and create a discovery doc inferred from
    // their declarations.
    endpoints.RegisterServiceWithDefaults(s)

    // I could also modify defaults for a specific method
    method := endpoints.MethodByName("MyService.DoSomething")
    // or endpoints.Method(s.DoSomething)

    // Default was POST because not all fields of Req struct are in "path" location, 
    // and not all fields have explicit location specified (either "path" or "query").
    // Otherwise, this would've been inferred as GET.
    method.SetHttpMethod("GET")

    // Default was "do_something/{a}/{d}"
    // (inferred from the method name and Req struct fields)
    method.SetPath("/do/{a}/foo-bar/{d}")

    // I could also move this method into a discovery "resources" section.
    // Otherwise, this would've been placed into the top-leve "methods" of discovery doc.
    method.SetResourceName("things")
    // "my.things" would work too (think of "drive.files.list")

    // Serve discovery and registered service methods over HTTP from the BackendService.
    http.Handle("/_ah/spi/", endpoints.HttpHandler)
    // or endpoints.HandleHttp()
}