NetFire Link Redirector API uses tenant residency, meaning only members of your organization can edit links 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 redirecting URL specification is referred to simply as a "redirect" (sometimes referred to as Redirect) in this documentation. Each tenant has one or more redirect. Each redirect has an identifier, referred to as {redirect}, that is automatically generated.

📘

Redirect IDs are read-only

They cannot be directly modified, and are automatically generated based on the redirect specification itself but are predictable. This means that if you modify a redirect's path or modifier, its Redirect ID will change!

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.

Redirects

There are two primary types of objects, Returns and Rewrites. Collectively, both types are referred to as a Redirect.

All Redirects have/support the following fields at a minimum:

Valid modifier Values

If no modifier is provided (or it is null), the default behavior is to match the path as a prefix (e.g. /foo will match /foo, /foo/bar, /foo/bar/baz, etc. provided no other matches exist for the path).

However, this matching behavior for path can be modified by one of the following modifiers:

• =: Match the path explicitly and literally (e.g. /foo will ONLY match /foo, not /foo/bar)
• ~: Case-sensitive regular expression-matched path
• ~*: Case-insensitive regular expression-matched path
• ^~: A regular expression for a prefix matchingpath (if no ~, ~*, or = matches first on a shorter match pattern)

🚧

Quote your regex patterns!

When using a ~, ~*, or ^~ modifier, it may be required (depending on the complexity of your path pattern) to explicitly enclose path in quotes within the JSON value (e.g. {"path": "\"^/foo\""}). If you notice URLs not matching properly or you're receiving validation errors on a Redirect creation/modification, your pattern may need quoting. This can be avoided by always using enclosed quoting regardless if using a regular-expression modifier.
If a modifier is not specified, the default behavior is to match based on treating path as a prefix (that is, {"path": "/foo", "modifier": ""} would match /foo/bar if there is no other /foo/bar match).

Be extra wary with escape sequences; depending on your language, /bar/\1 may instead be submitted to the server as e.g. /bar/<0x01>, which is probably not what you want. If you find yourself getting invalid JSON errors, you likely need to "escape the escape" (e.g. /bar/\\1) -- even if quoted.

Return

A Return object is a simple redirect from one URL to another.

In addition to all the fields in a Redirect, there are two additional fields:

Rewrite

A Rewrite object offers far more advanced rules attached to a single path match.

📘

Rewrites are for Complex Redirection

The majority of time, you'll likely want to use a Return instead of a Rewrite. They are much more simple and straightforward. However, a Rewrite allows you to internally modify relative URL paths without sending anything back to the user, which means e.g. particularly very optimized and performant aliases, for instance, to have multiple URL paths point to other URL paths which can then perform the final redirection.

It allows multiple rules with logic flow control (that is, you can specify multiple different redirects for a single path based on several criteria).

In addition to all the fields in a Redirect, there is one additional field:

Rewrite Rule

A Rewrite Rule contains a single rule to apply to a Rewrite. It consists of a map of three fields:

If no flag is provided, the default is to send the user a 302 return code with the redirect for absolute URLs, otherwise the URL rewriting will occur entirely internally and keep trying to match capture patterns (unless/until a flag is provided for a matched rule).

🚧

replace Modifies the URL Path

The evaluated replace directive for a rule, if matched, effectively internally modifies the URL path as provided by the user. This means if a capture matches the current internal URL path for a request, unless a flag is provided then further rules within the same path will act on that newly replaced URL path.

Valid flag Values

A Flag for a Rewrite Rule specifies how a given rule interacts with other rules for the same Rewrite. If no flag is specified, and replace is a relative URL path instead of a fully-qualified/absolute URL, then the rewrite rule checking will continue for the given path (unless last or break are provided to the rule).

If replace begins with http:// or https:// (i.e. is a fully-qualified/absolute URL), the redirect will be returned immediately -- as mentioned above, either with a 302 if no flag is provided, otherwise permanent or redirect can explicitly specify what type of return code.

The behavior for relative replace paths is controlled by one of the following flags:

• last: This exits the current path processing entirely and re-processes the URL as if the evaluated replace was provided by the user initially. This is useful if you wish to redirect e.g. https://links.domain.tld/foo 🡆 https://links.domain.tld/bar (assuming you are using https://links.domain.tld/ as your link redirection domain). It effectively aliases one path to another internally in a very performant manner.
• break: This stops further processing on this path. Likely you do not want to use this, as it will fall back to the default URL for your Redirector domain (if you have one defined). It is, however, useful if you wish your Redirector to act as if a path's subpath is not defined.
• redirect: This will return a 302 to the user to capture. This is useful if you wish to explicitly redirect a user to a different URL with a specific 302, or if you wish to explicitly redirect a user to a relative URL path (as otherwise it would continue processing other rules for the current path).
• permanent: Like redirect but with a 301 instead of a 302.

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.

Predictable Redirect IDs

🚧

For nerds only!

This section contains information that is not required to know for normal usage of the Link Redirector API, but is included as it can be utilized to further optimize usage of this API in high-performance implementations by e.g. not needing to capture the object after creation, or doing a GET for your entire tenant's redirects, etc.

While absolutely not necessary for normal usage of the Link Redirector API, a redirect's ID can be predicted. These are not secret and not used for any verification (beyond checking for duplicates), but they are unique per-tenant (even if the exact same redirection specification is provided to two different tenants) and serve as an unambiguous and guaranteed-unique identifier.

This also serves a benefit to completely eschew various quirks, differences, and ambiguities between different implementations of URL escaping across different languages.

To calculate the redirect ID, an 8-byte cSHAKE256 checksum is created (see NIST Special Publication 800-185 § 3.2). The following parameters are used:

X: [<modifier> ]<path>, as specified from the Redirect,stripped of surrounding whitespace
L: 64
N: (empty)
S: Link Redirector API: <TenantID>(where <Tenant ID> is your Tenant ID above)

This byte-value checksum is then represented as a lowercase hex string. This is the redirect ID.

As an example, a Return as such:

{
  "modifier": "",
  "path": "/",
  "target": "https://myorg.tld/",
  "return": 302
}

with tenant ID testtenant (thus S = Link Redirector API: testtenantand X = /) would evaluate to a redirect ID of d3bcac8d65944e6a.

Likewise, the following Return:

{
  "modifier": "=",
  "path": "/redir1",
  "target": "https://google.com/\\1",
  "return": 302
}

using the same tenant ID (thus S = Link Redirector API: testtenant and X = = /redir1) would evaluate to a redirect ID of 431087bbee3fc03a, and so forth.