The JVM SDK currently only supports legacy versions of Nitric prior to v1. This version is maintained for compatibility with existing projects and not recommended for new projects. New projects should be started using a supported SDK (presented automatically using the `nitric new` command) orget in touch to request an update to the latest version.

JVM - api()

Creates a new HTTP API.

import io.nitric.Nitric;

public class Application {
  public static void main(String[] args) {
    var api = Nitric.INSTANCE.api("public");

    Nitric.INSTANCE.run();
  }
}

Parameters

Name
name
Required
Required
Type
string
Description
The unique name of this API within the app. Subsequent calls to api with the same name will return the same object.
Name
options
Optional
Optional
Type
ApiOptions
Description
Additional options when creating the API.
Name
basePath
Optional
Optional
Type
String
Description
Base path for all routes in the API.
Name
middleware
Optional
Optional
Type
HttpMiddleware or List<HttpMiddleware>
Description
Middleware to apply to all routes and methods of the API.
Name
securityDefinitions
Optional
Optional
Type
Map<String, SecurityDefinition>
Description
Security definitions defined by this API.
Name
security
Optional
Optional
Type
Map<String, List<String>>
Description
Security rules to apply with scopes to the entire API. Keys must match a securityDefinition.

JWTSecurityDefinition Parameters

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
List<String>
Description
the aud that will be applied to JWT tokens from the issuer.

Notes

The middleware property on the options param is useful for applying universal middleware such as CORS headers or Auth, across an entire API from a single place.

Examples

Create an API

import io.nitric.Nitric;

public class Application {
  public static void main(String[] args) {
    var api = Nitric.INSTANCE.api("public");

    Nitric.INSTANCE.run();
  }
}

Create an API with universal middleware

import io.nitric.Nitric;
import io.nitric.faas.v0.Handler;
import io.nitric.faas.v0.HttpContext;
import io.nitric.resources.ApiOptions;

public class Application {
  static HttpContext authMiddleware(HttpContext ctx, Handler<HttpContext> next) {
    // perform auth validation
    return next.invoke(ctx);
  }

  public static void main(String[] args) {
    var apiOpts = new ApiOptions.Builder().middleware(Application::authMiddleware).build();

    var api = Nitric.INSTANCE.api("public", apiOpts);

    Nitric.INSTANCE.run();
  }
}

Notes

Middleware functions are supplied a 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 basePath option. In this example we ensure all routes start with /api/v1/ before the route specific path.

import io.nitric.Nitric;
import io.nitric.resources.ApiOptions;

public class Application {
  public static void main(String[] args) {
    var apiOpts = new ApiOptions.Builder().basePath("/api/v1").build();

    var api = Nitric.INSTANCE.api("private", apiOpts);

    Nitric.INSTANCE.run();
  }
}

Apply JWT authentication to an API

import io.nitric.Nitric;
import io.nitric.resources.ApiOptions;
import io.nitric.resources.JwtSecurityDefinition;

import java.util.List;
import java.util.Map;

public class Application {
  public static void main(String[] args) {
    var secureApiOpts = new ApiOptions.Builder()
      // security requirements for your API are defined here
      .securityDefinitions(Map.of(
        // define a security definition called 'user'
        "user", new JwtSecurityDefinition(
          "https://example-issuer.com",
          List.of("YOUR-AUDIENCES")
        )
      )).security(Map.of(
        // apply the 'user' security definition to the whole API with the scopes required.
        // in this case users will require the 'products:read' scope to access the API
        "user", List.of("products:read")
      )).build();

    var secureApi = Nitric.INSTANCE.api("secure", secureApiOpts);

    Nitric.INSTANCE.run();
  }
}