REST router

The rest integration provides an opinionated way to build a HTTP REST API with support for OpenAPI validations.

Trace attributes

The rest integration sets the following trace attributes:

  • http.client_ip
  • http.flavor
  • http.method
  • http.route
  • http.scheme
  • http.status_code
  • http.user_agent
  • http.wrote_bytes
  • net.sock.peer.addr
  • net.sock.peer.port
  • span.kind


http.client_ip: ""
http.flavor: "1.1"
http.method: "POST"
http.route: "/anything"
http.scheme: "http"
http.status_code: 202 "/anything"
http.user_agent: "insomnia/2023.2.2"
http.wrote_bytes: 21 "localhost" 8080
net.sock.peer.addr: ""
net.sock.peer.port: 50643
span.kind: "server"

Health check

The rest integration allows to pass a custom HTTP handler function for health check. It is exposed at GET /health.


$ curl --request GET \
    --url http://localhost:8080/health

By default if no custom function is passed, the rest integration retrieves the health status of each integration attached to the service running the rest integration, and returns the highest HTTP status code returned. This means if all integrations are healthy (status 200) but one is temporarily unavailable (status 503), the HTTP status code would be 503, and therefore the response body of the health check would be:

  "status": "Service Unavailable"


Install the Go module with:

$ go get

Simple example on how to import, configure, and use the integration:

import (


func main() {
  cfg := rest.Config{
    Address: ":8080",
    OpenAPI: rest.ConfigOpenAPI{
      Enabled:     true,
      Description: "./descriptions/openapi.yaml",

  router, err := rest.New(cfg)
  if err != nil {
    return err

  router.POST("/users/:id", func(rw http.ResponseWriter, req *http.Request) {
    params, ok := rest.ParamsFromContext(req.Context())
    if !ok {
      handlerfunc.NotFound(rw, req)

    userID := params["id"]
    // ...
    handlerfunc.Accepted(rw, req)

  if err := service.Start(); err != nil {

  if err := service.Close(); err != nil {

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the repository. Once we merge it, the changes will be reflected on the website the next time it is deployed. Thank you for your contributions!
Built by