Go - NewApi()

Creates a new HTTP API.

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

func main() {
  api := nitric.NewApi("public")

  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
WithSecurity()
Optional
Optional
Type
OidcOptions
Description
Security rules to apply with scopes to the entire API.
Name
WithMiddleware()
Optional
Optional
Type
ApiOption
Description
Name
middleware
Required
Required
Type
nitric.Middleware[apis.Ctx]
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.

OidcOptions Parameters

Name
Name
Required
Required
Type
string
Description
the name of the security definition
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.
Name
Scopes
Required
Required
Type
[]string
Description
the scopes that will be required to authenticate.

Examples

Create an API

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

func main() {
  api := nitric.NewApi("public")

  nitric.Run()
}

Create an API with universal middleware

import (
  "github.com/nitrictech/go-sdk/nitric"
  "github.com/nitrictech/go-sdk/nitric/apis"
)

func authMiddleware(next apis.Handler) apis.Handler {
  return func(ctx *apis.Ctx) error {
    if ctx.Request.Headers().Get("Authorization") == "" {
      ctx.Response.Status = 401
      ctx.Response.Body = []byte("Unauthorized")
      return nil
    }
    // perform additional auth checks

    return next(ctx)
  }
}

func main() {
  api := nitric.NewApi("private", apis.WithMiddleware(authMiddleware))

  nitric.Run()
}

Define middleware

func yourMiddleware(next apis.Handler) apis.Handler {
  return func(ctx *apis.Ctx) error {
    // Perform checks/actions prior to the route handler
    err := next(ctx)
    // Perform checks/actions after the route handler
    return err
  }
}

Notes

Middleware are higher-order functions that take a handler and return a handler. They can be used to perform actions before and after the route handler. Middleware can be used to perform actions such as logging, authentication, and error handling.

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 (
  "github.com/nitrictech/go-sdk/nitric"
  "github.com/nitrictech/go-sdk/nitric/apis"
)

func main() {
  v1Api := nitric.NewApi("public", apis.WithPath("/api/v1/"))

  nitric.Run()
}

Apply JWT authentication to an API

import (
  "github.com/nitrictech/go-sdk/nitric"
  "github.com/nitrictech/go-sdk/nitric/apis"
)

func main() {
  defaultOidcRule := apis.OidcRule(
    "user",
    "https://example-issuer.com/.well-known/openid-configuration",
    []string{"YOUR-AUDIENCES"},
  )

  secureApi := nitric.NewApi(
    "secure",
    // apply the security definition to all routes in this API.
    apis.WithSecurity(defaultOidcRule([]string{})),
  )

  nitric.Run()
}