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()
}
Last updated on Dec 5, 2024