Contact Support

Getting Started with WAF API

NetFire WAF API uses tenant residency, meaning only members of your organization can edit configurations for your organization. All API endpoints start with your tenant identifier.

👍

Your tenant identifier is provided by NetFire.

If you have not received it, please contact support by emailing [email protected] or submit a request directly to our help desk.

Documentation will refer to this in URLs as {tenant}. Be sure to replace this (including the braces) with your actual tenant identifier. It is case-sensitive.

Each specific site that is passed through the WAF is referred to as a "host" (sometimes referred to as Host) in this documentation. Each tenant has one or more hosts. Each host has an identifier, referred to as {host}, that must be unique for your tenant. This same HostID will be served as a subdomain for your tenant's domain.

Content Type

All body content is JSON, which the Content-Type of application/json. Likewise, all requests sending a body (POST, PATCH) must specify Content-Type: application/json.

If this header is missing, an HTTP 415 Unsupported Media Type status will be returned.

If invalid JSON content is passed to the API, an HTTP 422 Unprocessable Entity status will be returned.

Host

A Host object specifies configuration details of a Host.

Currently there are only two fields:

  • name: This should be the exact same string as the HostID
  • target: This is the target to reverse proxy to. It must be in URL format. Only http and https schemes are supported. If specifying an IP address as a target, it must have an explicit path (e.g. http://198.51.100.5/, not http://198.51.100.5), thus "magic" reverse proxying (see note below) will not work for IP-based targets.

📘

An explicit URL path in target may be specified.

The default behavior if no URL path is specified in a target is to automatically apply the request URL path to the target. For example, assuming an externally exposed site pub.domain.tldto a target http://foo.domain.tld:

http://pub.domain.tld/foo/bar 🡆 http://foo.domain.tld/foo/bar

However, if a URL path is specified in a target, for example a target of http://foo.domain.tld/subdir, then the original request's URL path will be appended. e.g.:
http://pub.domain.tld/foo/bar 🡆 http://foo.domain.tld/subdir/foo/bar

Errors

Most errors you encounter, if any, should have an informative error (in JSON format) in the body and an appropriate return status code that's documented for the endpoint and URL path you're using.

If trying to access an endpoint that does not exist, you will receive an HTTP 404 Not Found status returned.

If you receive an HTTP 500 Internal Server Error status returned, however, then please contact support by emailing [email protected] or submit a request directly to our help desk. Include:

  • The content of the X-Correlation-ID header in the response headers from the server (This is the most important piece of information!), and
  • The request headers, body content (if applicable), and full URL you are using (if possible).

It is recommended that you log the X-Correlation-ID header's value in your application in the event that you are investigating an issue in the past.

Version

The exact API version can be determined by the X-Api-Version header. The API server software follows Semantic Versioning, and this is reflected by the v# of the API documentation.

For example: X-Api-Version: v1.1.1 means the server is running API version 1.1.1. Because API-changing features are limited to only major version revisions in Semantic Versioning, you can be certain that the documentation for API endpoint v1 can be applied to any API version 1.x.x.

📘

Features

Features may be added under the same major version, as long as they don't break existing functionality of the existing version specification. If a feature is being changed or removed in a way that may break your implementation/programs/scripts, it will be reserved for a different major release.