Introduction

NetScaler Next-Gen API is a powerful modern RESTful API that allows you to programmatically configure NetScaler in a simple and intuitive way. It is based on a declarative, desired state and application-centric interface, and aims to abstract away and simplify many of the low-level complexity of traditional NetScaler configurations, making it more suitable to application developers even those who are not networking or ADC experts.

The core concept in the Next-Gen API is the application. All the configuration elements pertaining to the same application are grouped together, making it easy and safe to apply changes atomically.

To illustrate the new API, let’s start with a simple configuration use case of creating a NetScaler load-balancing configuration with a VIP and a couple of backend servers

POST /mgmt/api/nextgen/v1/applications

{
  "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "default_certificate_ref": "app1_cert",
    "servers": [
      "192.168.10.11",
      "192.168.10.14"
    ]
  }
}
<!--NeedCopy-->

With this one API call, we have fully configured this load-balancing use case. We’ll cover how we got a certificate reference later in the document.

Let’s say we want to update the configuration to add more servers or make other changes. We can simply issue another API call to add more servers as follows:

PUT /mgmt/api/nextgen/v1/applications/app1

{
  "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "default_certificate_ref": "app1_cert",
    "servers": [
      "192.168.10.11",
      "192.168.10.14",
      "192.168.10.15",
      "192.168.10.16"
    ]
  }
}
<!--NeedCopy-->

Notice that we have provided the new “desired state” of the application in the update API, which now contains 4 servers rather than 2.

Subsequent sections of this documentation cover advanced use case scenarios, which includes content switching, configurations involving multiple VIP addresses, and diverse port setups.

Comparison to Nitro API

While the NetScaler traditional Nitro API has been very successful in providing a REST API for interfacing programmatically with NetScaler and unlocking all its features, it ultimately is an API that mirrors the internal NetScaler processing constructs, the NetScaler CLI structure, and reflects the low-level complexity and idiosyncrasies of the NetScaler configuration model making its usage intimidating to many new users.

The Next-Gen API takes a new approach of a user-centric design, starting from the common use cases and patterns that customers often try to realize on NetScaler, and making these use cases explicit and very simple to create. It also aims to be developer-friendly by adopting consistency in behavior and conventions, a logical structure, with modern desired state semantics.

Using the Nitro API, the simple load-balancing configuration shown above, would require 6 API calls, and assumes acquaintance with concepts and APIs for creating vservers, servicegroups, services and bindings between these entities. Slightly more complex use cases can require tens of API calls, with the user or the calling application responsible for understanding the proper order of calling these APIs and handling any mid-workflow errors.

The other difference with the Nitro API has to do with the processing infrastructure. The Next-Gen API uses a new modern config infrastructure on NetScaler that segregates the config validation and commit stage from applying the config to the data plane. What this means for users is faster API processing. The config is considered “committed” once it’s validated and stored on a persistent DB. In the background and asynchronously, the Next-Gen config infrastructure will translate and apply the latest config changes from the DB to the NetScaler data plane (packet engines).

Configuration Views

Both the Next-Gen API and Nitro API are supported on NetScaler, and configurations can be created using both. Configurations created with Next-Gen API can only be modified using Next-Gen API. However, these configurations can be viewed in read-only mode through the CLI or Nitro API. To switch to the Next-Gen API config view, use the following CLI command:

switch ns configview NEXTGENAPI
<!--NeedCopy-->

In this view, you can only see configurations created through Next-Gen API. By default, the config view is set to ALL, which provides a read-only view of Next-Gen API configurations along with an unrestricted view of configurations created using NetScaler CLI, GUI, or Nitro API. Additionally, there is the CLASSIC config view, where you can view and modify configurations created using the NetScaler CLI, GUI, or Nitro API.

Note:

Configview is a session-level setting that applies only to the current user session (CLI or Nitro session) and does not affect all users globally.

Configuration created through Next-Gen API is not saved in ns.conf when you run the save ns config command. Next-Gen API configuration is persistent and remains intact after a reboot.

The following behavior is observed for different levels of the clear ns config <level> command:

To delete all Next-Gen API resources at once, use the following CLI command:

clear ns nextgenapi
<!--NeedCopy-->

To delete individual resources like applications or certificates, use the respective Next-Gen DELETE APIs.

System Requirements

Next-Gen API is available on NetScaler release 14.1 12.30.

If you are using NetScaler VPX, please ensure you have at least 4GB RAM.

Note:

Currently, NetScaler standalone and HA deployment is supported on MPX and VPX. Cluster is not yet supported.

Enabling Next-Gen API on NetScaler

Before using Next-Gen API, you need to enable it first on NetScaler using the CLI:

> enable ns nextgenapi

ERROR: Operation not permitted [To use nextgenapi you need to enable SSL defaultprofile. CLI CMD: set ssl parameter -defaultProfile ENABLED]
<!--NeedCopy-->

This will fail if you don’t already have defaultProfile enabled for SSL as Next-Gen API requires this. Once you configure the default profile for SSL, retry this command.

You can verify the status of Next-Gen API using this command:

> show ns nextgenapi

Next-Gen API State: STARTED

>
<!--NeedCopy-->

Now, you can start exploring its new APIs.

API reference

Next-Gen API reference documentation is specified using the OpenAPI specification. The same specification used for documentation is used to generate API server stubs to ensure that the documentation always reflects the actual specification.

You will also find multiple examples of each API endpoint in the reference documentation to illustrate usage. You can browse the API documentation on the NetScaler GUI under the Documentation tab, and download a copy of the YAML OpenAPI specification from the Downloads tab.

Authentication

Next-Gen API requires users to first authenticate using a valid user account on NetScaler in order to obtain a session token. Once authenticated, the returned cookie needs to be included in all subsequent API calls in the form of a cookie.

Use the following API for authentication and obtaining a session token.

POST /mgmt/api/nextgen/v1/login

{
  "login": {
    "username": "user1",
    "password": "verysecret"
  }
}
<!--NeedCopy-->

If authentication is successful, the returned status code is 200, and the response will include a Set-Cookie header that will set a cookie named sessionid which contains a valid session token to be used for subsequent API calls.

200 OK
Set-Cookie: sessionid=%23%23B2A100C6D1F36AAE2......A50FA2C576171;
Path=/mgmt/api/nextgen/v1
<!--NeedCopy-->

You can also specify the duration of the created session, by adding a timeout attribute to the login request as shown below:

POST /mgmt/api/nextgen/v1/login

{
  "login": {
    "username": "user1",
    "password": "verysecret",
    "timeout": "5min"
  }
}
<!--NeedCopy-->

In the above example, we are requesting a session that will timeout after 5 minutes of inactivity.

Note:

In Next-Gen API, all values that represent time duration, will always have the unit of time as part of the value. For example, a 5 minutes value, can be given as 5m, 5min, 300s or 300sec.

After a successful login, subsequent API requests should include the sessionid cookie header. For example, to list all applications, the following API call with the sessionid cookie is made:

GET /mgmt/api/nextgen/v1/applications

Cookie: sessionid=%23%23B2A100C6D1F36AAE2......A50FA2C576171
<!--NeedCopy-->

Next-Gen API also provides an explicit call to logout from the session, which invalidates the session token.

POST /mgmt/api/nextgen/v1/logout

Cookie: sessionid=%23%23B2A100C6D1F36AAE2......A50FA2C576171
<!--NeedCopy-->

The following is a successful response to the logout API call:

200 OK

Set-Cookie: sessionid=deleted; expires=Thu, 01-Jan-1970 00:00:01 GMT; Max-Age=0; Path=/mgmt/api/nextgen/v1
<!--NeedCopy-->

The response doesn’t contain a body payload. Once successfully logged out, the session cookie is no longer valid.

Note:

Next-Gen API and Nitro API share the same system users. You can configure users who can access the appliance using regular NetScaler CLI or GUI.

Role-Based Access

Next-Gen API allows you to define the set of API endpoints that a user can call through the ability of defining roles, and associating allowed operations and API endpoints with each role. You can then assign these roles to user groups.

The following API creates a role called app-admins that allows users all operations on the applications resources.

POST mgmt/api/nextgen/v1/roles/apps-admin-role

{
  "role": {
    "name": "apps-admin-role",
    "permissions": [
      {
        "method": "ALL",
        "resources": "/applications/.+"
      }
    ]
  }
}

<!--NeedCopy-->

The role has a name and a set of permissions. Each permission specifies the resource URLs allowed (using a regular expression) along with the HTTP methods on these resources. In the example above, the role allows all HTTP methods (GET, POST, PUT, DELETE) on any application by specifying the regular expression “/applications/.+”.

Once the role is defined, it can be assigned to one or multiple user groups. The following API assigns the role “apps-admin-role” to the user group “apps-admin-grp”.

POST mgmt/api/nextgen/v1/groups/apps-admin-grp/roles

{
  "role": "apps-admin-role"
}
<!--NeedCopy-->

Once a role is assigned to a group, it cannot be deleted until it is dissociated from any user groups where it is being used. You can remove the association between a user group and a role using the following API

DELETE mgmt/api/nextgen/v1/groups/apps-admin-grp/roles/apps-admin-role

<!--NeedCopy-->

Now, when a user logs in through Next-Gen API, their user groups are retrieved, and based on the roles for these groups, the logged in user will be restricted to the API endpoints allowed by these roles.

If a user tries to access an API endpoint for which they are not authorized, they will receive a 401 Not Authorized error.

Note:

Configuring user accounts, user groups and managing user authentication on NetScaler, including configuring external authentication such as LDAP or RADIUS can continue to be managed using NetScaler CLI, GUI, or Nitro API. Please refer to NetScaler documentation for these topics.

Configuration Paradigms

NetScaler Next-Gen API supports two complementary configuration paradigms designed to address different use cases and user requirements:

• Application-Centric Model: The application-centric approach groups all configuration elements related to an application together, making it easy to manage complete application configurations atomically. This model is ideal for common use cases and provides a simplified, high-level abstraction.

For detailed API reference information about the Application-Centric model, including resource types, API structure, and semantics, see the Application-Centric API Reference.

• Entity-Centric Model (Config Sets): For scenarios requiring full access to NetScaler’s feature set or granular control over individual Nitro entities, Config Sets provide a declarative mechanism to define any NetScaler configuration. This bridges the gap between the power of Nitro and the simplicity of Next-Gen API’s desired-state model.

For detailed information about Config Sets, including use cases, examples, and best practices, see the Config Sets Guide.

API Calls Structure

Next-Gen API resources and calls all follow a consistent format.

<http_verb> /mgmt/api/nextgen/v1/<resource_type>/<resource_name>
<!--NeedCopy-->

For example to retrieve the details of an application called my_app:

GET /mgmt/api/nextgen/v1/applications/my_app
<!--NeedCopy-->

If you want to retrieve all applications, you omit the resource_name part:

GET /mgmt/api/nextgen/v1/applications
<!--NeedCopy-->

Some resources are sub-resources of existing resources, in which case, the URL follows this format:

<http_verb> /mgmt/api/nextgen/v1/<resource_type>/<resource_name>/<subresource_type>/<subresource_name>
<!--NeedCopy-->

For example to retrieve the backends of an application called my_app, you use the following API call:

GET /mgmt/api/nextgen/v1/applications/my_app/backends
<!--NeedCopy-->

To retrieve a specific backend named metadata_servers, you use the following call:

GET /mgmt/api/nextgen/v1/applications/my_app/backends/metadata_servers
<!--NeedCopy-->

The supported HTTP verbs are the following:

The request and response payloads are expressed in JSON format.

Resource Types and Resources

Next-Gen API config model is made up of a set of resource types. The following are the resource types currently supported:

• Application
  • Backend
    • Server
  • Frontend
    • Listener
  • Route
• Certificate
• Filter Value Set
• Responder HTMLPage
• HTTP Callouts
• Config Sets

Resource types are organized in a hierarchy: some resource types are subtypes of others as indicated by the indentation above. For example, frontends and backends are subtypes of the application resource type. And servers is a subtype of a backend. This hierarchy is reflected in the URL representation of a resource.

/mgmt/api/nextgen/v1/applications/{application_name}/backends/{backend_name}/servers
<!--NeedCopy-->

Here the URL reflects that servers is a subresource of a specific backend, which is a subresource of a specific application.

The following table describes the role of each resource supported in the API:

Listeners

The listener has the following attributes:

Applications

In summary, a simple LB application can have the following attributes:

References between resources

The resource’s name specified during creation can be used to refer to it from other resources. We used this already to refer to a certificate from an application payload.

Next-Gen API uses the naming convention <resource_type>_ref for attribute names that carry a reference to an existing resource. For plural references, the naming convention is <resource_type>_refs. For example, the attribute certificate_refs of an application resource.

Desired State Semantics

Next-Gen API allows users to specify the “desired state” of a resource, and let the system figure out how to bring the configuration from its “current state” to that “desired state”.

For example, when the user wants to ensure that an application called “app1” with a certain configuration is present on NetScaler, they can simply issue the following API call:

POST /mgmt/api/nextgen/v1/applications/app1

{
  "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "protocol": "HTTP",
    "servers": [
      "192.168.10.11",
      "192.168.10.14"
    ]
  }
}

<!--NeedCopy-->

It doesn’t matter whether application “app1” already exists or whether it’s newly created. Next-Gen API will ensure to create it if it doesn’t exit or to update it with the specified configuration if it already exists.

Another example would be configuring the backend servers of an application.

PUT /mgmt/api/nextgen/v1/applications/app1/backends/tier1/servers

{
  "servers": [
    "192.168.10.11",
    "192.168.10.14",
    "192.168.10.15",
    "192.168.10.16",
    "192.168.10.17"
  ]
}

<!--NeedCopy-->

It doesn’t matter whether there are servers already in the backend called “tier1” or not. This API will ensure that after it’s executed the backend “tier1” will have the specified servers in the request. If some of these servers are already present, then only the missing servers are added. If there are servers that are not specified in the request, then these servers will be removed from the backend.

The “desired state” semantics frees the user from having to track the current state of resources, and having to imperatively specify the steps required to bring the resource to the user’s desired state.

Incremental Change Semantics

While “desired state” is very useful for simplifying the API client, it is also desirable in some cases to avoid specifying the whole resource state on each API call, and only specify what needs to be changed (added or removed). Taking the previous example, if the backend “tier1” has a 1,000 servers currently, and we want to add 1 extra server, it’s bulky to specify 1,001 servers in the request, and would be more efficient to simply specify the new server to be added. Next-Gen API also accomodates this usage pattern by providing an explicit API call to change a resource’s state explicitly.

For example, to add a new server to the backend “tier1” (without respecifying all the servers that are already part of this backend), we can use the following API call:

POST /mgmt/api/nextgen/v1/applications/app1/backends/tier1/servers

{
   "server": "192.168.10.17"
}
<!--NeedCopy-->

Similarly, if we want to create a new application called “app1”, and we want the operation to fail if “app1” already exists, we can use the following POST API:

POST /mgmt/api/nextgen/v1/applications

{
 "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "protocol": "HTTP",
    "servers": [
      "192.168.10.11",
      "192.168.10.14"
    ]
  }
}
<!--NeedCopy-->

The difference with the “desired state” API described in the previous section is a subtle one: we ommitted the application name “app1” from the URL.

POST /mgmt/api/nextgen/v1/applications/app1
<!--NeedCopy-->

Application actions

The following actions are supported for the application:

Disable/Enable Application

To disable the application so it doesn’t serve any traffic, use the following API call:

POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/disable
<!--NeedCopy-->

To enable the application so it can serve traffic, use the following API call:

POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/enable
<!--NeedCopy-->

The enable/disable application APIs are reflected in the configured_state parameter in the application health response.

Note:

Disable/Enable APIs are also supported for application subcomponents such as frontends, listeners, backends, and servers. For more information, see API Exploration section of the document.

Uninstall/Install Application

To uninstall the application, meaning the application config is removed from NetScaler data plane(packet engines) but remains on Next-Gen. , use the following API call:

POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/uninstall
<!--NeedCopy-->

This operation is typically useful when there are discrepancies observed in data plane behavior due to config inconsistencies, and you want to clear the config from the data plane and reinstall it later.

To install the uninstalled application, use the following API call:

POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/install
<!--NeedCopy-->

Error Handling

Next-Gen API uses HTTP Status Codes to signal success or failure. Successful API responses are identified by the HTTP status codes 200 or 201.

Below are the list of HTTP Status codes that can be returned by the API and their meaning:

When the HTTP status code indicates an error (400-500 range), the response body contains the details of the error. For example, below is the response body for a 400 error returned, indicating the request payload is missing a required attribute (certificate reference).

{
    "errorcode": 400,
    "errormessage": "Validation Error",
    "details": [
        {
            "instance": "{'name': 'color_app', 'virtual_ip': '10.102.201.171', 'protocol': 'HTTPS', 'service_port': 8010, 'servers': ['10.102.201.166', '10.102.201.167']}",
            "message": "'certificate_ref' is a required property for 'protocol':'HTTPS'"
        }
    ]
}

<!--NeedCopy-->

The following table enumerates the mapping between HTTP Status codes and the internal error codes and error messages:

Note:

Please refer to the OpenAPI spec for an up-to-date information on all the valid errorcode values that can be returned by the API.