Skip to main content

Forward API

Introduction​

The Forward API can help you automate tasks in the Forward Platform and integrate it with other tools.

Use cases include:

  • Triggering network Snapshot collection
  • Automating Check and Alias creation/updates
  • Building custom dashboards and alerts
  • Exporting network Snapshots for sharing or archival purposes

Each API section includes an OpenAPI description that can be used to generate client SDKs to help speed up integration. If you use several sections, you might prefer our combined description:

  • Forward combined OpenAPI description: YAML | JSON

If you have any questions or feedback, please contact us at support@forwardnetworks.com. We’d love to hear from you. Enjoy!

Authentication​

API requests use Basic authentication. This means that a Base64-encoded credential pair is sent in the Authorization header of each request, as in Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=. Common tools and libraries such as curl, Requests, and Axios can format this header. A Linux shell can also Base64-encode:

echo -n username:password | base64

API tokens (access key + secret key) are the preferred credential type for API requests. Traditional credentials (username + password) are also accepted for most account types, but not for SSO (SAML) accounts. You can generate API tokens in the application on the account settings page. API tokens are different from traditional credentials in a few key ways:

  1. API tokens can’t be used to log in.
  2. API tokens are longer than most passwords and are created using a cryptographically strong random number generator to protect against brute-force password-guessing attacks.
  3. API tokens satisfy the two-factor authentication (2FA) requirement in organizations that use 2FA.
  4. API tokens keep working even if you change your password.
  5. API tokens can be deleted at any time.

If you write a program that uses the API with a fixed set of credentials, consider creating a dedicated user account for that purpose—one that has only the access permissions it needs.

To avoid sending credentials unencrypted through the network, use HTTPS.

HTTP Verbs​

API operations use conventional HTTP verbs/methods.

VerbPurpose
GETRetrieve a resource or multiple resources (a collection).
HEADRetrieve only the HTTP headers for resources normally retrieved using a GET request.
POSTCreate a resource or multiple resources.
PATCHUpdate resources with partial JSON data. Only properties that should change need be supplied.
PUTReplace a resource or collection (or create it if it doesn’t exist yet).
DELETEDelete a resource or collection.

HTTP Status Codes​

API responses use standard HTTP status codes. Each operation’s documentation identifies the status code that it uses to indicate success (typically 200 OK or 204 No Content) and any notable client (4xx) error codes that it might return.

An error response’s body is an ErrorInfo JSON object whose message property describes the problem. Some 4xx error codes that can occur for nearly every API operation are listed below.

CodeDescription
400 Bad RequestThere was an error in the syntax or semantics of the request. See the message property in the response body for details.
401 UnauthorizedAuthentication is required and has failed or has not yet been provided. See Authentication.
403 ForbiddenThe authenticated user account does not have the necessary permissions for the operation.
404 Not FoundThe requested resource could not be found. Check the request path and any identifiers in the request for typos.
405 Method Not AllowedThe request method is not supported for the requested resource. A PUT request to a read-only resource, for example, would cause this error.
406 Not AcceptableThe request’s Accept header doesn’t permit the operation’s response format (typically application/json).
415 Unsupported Media TypeThe request’s Content-Type header doesn’t match the operation’s required type (typically application/json).

Rate Limiting​

Forward limits the number of API requests that each user account can make. On Forward-hosted (SaaS) deployments, the limit is 2,000 requests per minute per user account, measured over a rolling 60-second window. The limit protects the shared service: it prevents a single user’s automation from degrading availability or performance for others, whether in the same organization or in a different one.

Self-hosted deployments don’t enforce an API rate limit by default, but they can be configured to if desired. Ask Forward Support how.

When a request exceeds the limit, the response has the 429 Too Many Requests status and a Retry-After: <seconds> header indicating how long to wait before retrying. Exceeding the limit also places the user account in a brief lockout, during which every request from that account is rejected with a 429 response.

  • On Forward-hosted (SaaS) deployments, the lockout lasts 1 minute from the moment the limit is exceeded. (Self-hosted deployments can configure the lockout duration.)
  • The lockout is fixed: requests made during it are rejected (each 429 includes a Retry-After header with the seconds remaining) but do not extend or reset it. Continuing to send requests while locked out does not prolong the lockout.

Rate limits are rarely encountered or even approached under normal conditions. Here are some best practices to help you avoid them:

  • On a 429, honor the Retry-After header: wait at least the number of seconds it specifies before retrying.
  • In scripts and other API integrations, don’t retry requests after an error that is not temporary in nature, such as 400 Bad Request.
  • For transient errors with no Retry-After header (such as timeouts or 503 Service Unavailable), retry with exponential backoff.
  • Use Webhooks rather than polling if possible. When polling is required, choose a conservative poll interval and poll a specific resource rather than repeatedly listing large collections.
  • Retrieve data in bulk when you can, such as with a single NQE query or a Snapshot export instead of many per-device, per-interface, or per-object requests.
  • Run independent automation workflows under separate user accounts where possible. Because the limit is per account, this approach isolates workflows so one workflow can’t consume another’s request budget. It also gives cleaner attribution of API calls and audit trails to each workflow.

Change Policy​

The Forward API is designed to be stable and reliable. We understand the importance of these qualities. At the same time, we aim to continually improve the API and deliver new functionality. To these ends, we’ve adopted this change policy:

  • Non-breaking changes are common and are introduced without advance notice. Non-breaking changes include:
    • Adding a new API operation
    • Adding an optional new query parameter to a request
    • Adding an optional new JSON property in a request
    • Adding a new JSON property in a response
    • Adding a new possible value for a JSON property in a request or response
  • Breaking changes are rare and avoided if at all possible. When one is deemed necessary, a breaking change will be announced in the API Release Notes at least three (3) releases (approx. 3 months) in advance. The announcement will include instructions for minimizing the impact of the change. The affected API operations, parameters, and properties will be marked as deprecated in this document during the 3 releases of advance notice. We also make every effort to identify customers who will be affected and personally and proactively notify them. Breaking changes include:
    • Removing an API operation
    • Removing a JSON property from a response
    • Requiring a query parameter or JSON property in a request