Concepts

Concepts

This page dives into the mechanisms samb offers to make you more efficient at building a RESTful HTTP API.

Providers

Providers, in samb, offer a simple way to add variables to your request's scope, following the factory method pattern. These variables can be used as parameters in your handler's invocation.

Guidelines

Provider factory functions have two parameters and must return a pointer. The two parameters consist of :

• r : *http.Request - The current request.
• w : http.ResponseWriter - The response writer to the current request.

The pointer, can point to any type.

Routing

samb provides a structured language to build APIs. Routing in samb is written in a clear, readable and layered format.

Sub routing

With samb, you can nest routes within other routes. These nested routes are referred to as sub routes, within this wiki. A sub route's request path would be its path, prefixed by the paths of its parent routes. Have a look at the YAML example below for a better idea :

# SAMB endpoint declarations in YAML.
routes:
  provide: ["r","w"]
  route :
    - method : "*" # asterisk to indicate parent route should allow all HTTP request methods.
      path : /Foo
      route :
        - method : GET
          # Uncomment the following line
          # To use an absolute path :
          # strict : true
          path : /Bar/ # full path will be GET /Foo/Bar/
          handler : w.Write([]byte("Hello World"))

The handler used with your route will receive a custom URL path. For example, if the route above was requested with path /Foo/Bar/ID, the URL of the request sent to the handler will be ID. This simplifies the process of retrieving URL parameters. To disable to feature, and use an absolute path with no parameters, set strict to true.

Provider Inheritance

Providers provided in a sub route's parent can be used within said sub route.

Recovery

With samb, you can declare functions to be executed if a handler panics during execution. With the safety net of the samb recovery directives, programmers can structure error handling, in a clear, readable and layered format. This also means that you can use panic(reason string) without crashing your server.

Guidelines

Recovery functions must be placed in your project's generated package api. The recovery functions must be internal, relative to package api.

The signature of a samb recovery function (in Go) is as follows :

func xXX(w http.ResponseWriter, r *http.Request, m string)