x-ntx-host

Use the x-ntx-host Specification Extension to override your host The domain name of the third-party API's URL. definition for a specific operation A single request to a third-party API. Operations often become actions in the workflow designer..

Tip: You may also want to use x-ntx-basePath or x-ntx-connection-properties.

How to use x-ntx-host

Add the key x-ntx-host with the value of the new domain you want to use in the HTTP method The HTTP action to perform on the endpoint, such as GET, POST, DELETE, PUT. In defined inside the operation's path object in the OpenAPI specification. you want to override the host of.

Tip: This specification extension supports placeholders.

Where to use x-ntx-host

You can use x-ntx-host:

  • At the document level, where it overrides the standard host declaration for the whole document.
  • Inside the HTTP method object of an operation, where it overrides the document's host declaration for all operations on the same path as the specified operation.
 

"/examplepath": {
  "post": {
    "summary": "Post request",
    "description": "Request to httpbin",
    "operationId": "get-httpbin",
    "x-ntx-host": "operation-specific-host.example.com",
    "produces": [ "application/json" ],
    "parameters": [],
    "responses": {
      "200": {
         "description": "OK",
      }
    }
  }
}		
		

Using placeholders

Sometimes you need to use a different host for different connections. For example, your third-party service may use different domains based on the geographic location of the account.

To avoid hard-coding multiple OpenAPI Specifications with each possible host , you can use the x-ntx-connection-properties specification extension to store a different host for each connection in Nintex Automation Cloud. When the workflow designer creates a new connection, they are prompted to add their host domain along with their connection credentials. Nintex Automation Cloud stores this information with their connection details.

In the OpenAPI Specification, use the connection-properties placeholder in {{double braces}} for the host value to tell Nintex Automation Cloud to use the connection-specific host.

For more information on using the connection-properties specification extension, see x-ntx-connection-properties.

{
  "host": "login.example.com",
  "basePath": "/",
  "x-ntx-host": "/{{subdomain}}.example.com",
  "securityDefinitions": {
    "basicAuth": {
      "type": "basic",
      "x-ntx-connection-properties": {
        "type": "object",
        "properties": {
          "subdomain": {
            "type": "string",
            "title": "Subdomain"
          }
        },
        "required": ["subdomain"]
      }
    }
  }
} 

Limitations

The x-ntx-host extension must be added inside an HTTP method object, not the parent path The part of the URL after the hostname that directs the request to a specific resources within the host. For example, the section after "example.com" in http://example.com/this/is/a/path. object, however any x-ntx-host extension added is applied to all HTTP methods for that path.

Example: If you have a path /example.php that has GET, POST and PUT operations, and you use x-ntx-host to override the POST operation with alternative.example.com, the GET and PUT operations will also use alternative.example.com. You cannot then add a x-ntx-host definition to the GET operation to override it to a different host.