Go - NewApi()

Creates a new HTTP API.

import (
  "fmt"

  "github.com/nitrictech/go-sdk/nitric"
)

func main() {
  api, err := nitric.NewApi("public")
  if err != nil {
    return
  }

  nitric.Run()
}

Parameters

Name
name
Required
Required
Type
string
Description
The unique name of this API within the app. Subsequent calls to NewApi with the same name will return the same object.
Name
options
Optional
Optional
Type
...ApiOption
Description
Additional options for the API. See below.

API options

Name
WithPath()
Optional
Optional
Type
ApiOption
Description
Sets a base path for all the routes in the API.
Name
path
Required
Required
Type
string
Description
Base path for all routes in the API.
Name
WithSecurityJwtRules()
Optional
Optional
Type
ApiOption
Description
Sets a security JWT rules on the API.
Name
name
Required
Required
Type
string
Description
The name of the security rule.
Name
rule
Required
Required
Type
JwtSecurityRule
Description
The properties of the JWT security rule.
Name
WithSecurity()
Optional
Optional
Type
ApiOption
Description
Name
name
Required
Required
Type
string
Description
The name of the security rule.
Name
scopes
Required
Required
Type
[]string
Description
The security rules scopes.
Name
WithMiddleware()
Optional
Optional
Type
ApiOption
Description
Name
middleware
Required
Required
Type
HttpMiddleware
Description
The middleware (code) that should be run on all requests to the API. Useful for applying universal middleware such as CORS headers or Auth, across an entire API from a single place.

SecurityDefinition Parameters

Name
JwtSecurityRule
Optional
Optional
Type
Description
Name
kind
Required
Required
Type
string
Description
value must be jwt
Name
issuer
Required
Required
Type
string
Description
the issuer for the JWT tokens e.g. https://account.region.auth0.com
Name
audiences
Required
Required
Type
[]string
Description
the aud that will be applied to JWT tokens from the issuer.

Examples

Create an API

import (
  "fmt"

  "github.com/nitrictech/go-sdk/nitric"
)

func main() {
  api, err := nitric.NewApi("public")
  if err != nil {
    return
  }

  nitric.Run()
}

Create an API with universal middleware

import (
  "fmt"

  "github.com/nitrictech/go-sdk/faas"
  "github.com/nitrictech/go-sdk/nitric"
)

func authMiddleware(ctx *faas.HttpContext, next faas.HttpHandler) (*faas.HttpContext, error) {
  // Perform auth validation
  return next(ctx)
}

func main() {
  api, err := nitric.NewApi("private", nitric.WithMiddleware(authMiddleware))
  if err != nil {
    return
  }

  nitric.Run()
}

Define middleware

func authMiddleware(ctx *faas.HttpContext, next faas.HttpHandler) (*faas.HttpContext, error) {
  // Perform auth validation
  return next(ctx)
}

Notes

Middleware functions are supplied an HttpContext object and a next() function which calls the next middleware in the chain.

Create an API with a base path

If you need to put all the routes in your api below a shared base path, you can do that with the WithPath option. In this example we ensure all routes start with /api/v1/ before the route specific path.

import (
  "fmt"

  "github.com/nitrictech/go-sdk/nitric"
)

func main() {
  v1Api, err := nitric.NewApi("public", nitric.WithPath("/api/v1/"))
  if err != nil {
    return
  }

  nitric.Run()
}

Apply JWT authentication to an API

import (
  "fmt"

  "github.com/nitrictech/go-sdk/nitric"
)

func main() {
  secureApi, err := nitric.NewApi(
    "secure",
    // define a security definition called 'user'
    nitric.WithSecurityJwtRule("user", nitric.JwtSecurityRule{
      Issuer: "https://example-issuer.com",
      Audiences: []string{ "YOUR-AUDIENCES" },
    }),
    // You can optionally apply security rules to the entire API
    nitric.WithSecurity(
      // apply the user security definition to the whole API
      "user",
      // Optionally apply required scopes to this api
      // in this case users will require the 'products:read' scope to access the API
      []string{"products:read"},
    ),
  )
  if err != nil {
    return
  }

  nitric.Run()
}