Forward API

Introduction

The Forward Networks 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 Networks 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.

Verb	Purpose
GET	Retrieve a resource or multiple resources (a collection).
HEAD	Retrieve only the HTTP headers for resources normally retrieved using a GET request.
POST	Create a resource or multiple resources.
PATCH	Update resources with partial JSON data. Only properties that should change need be supplied.
PUT	Replace a resource or collection (or create it if it doesn’t exist yet).
DELETE	Delete 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.

Code	Description
400 Bad Request	There was an error in the syntax or semantics of the request. See the message property in the response body for details.
401 Unauthorized	Authentication is required and has failed or has not yet been provided. See Authentication.
403 Forbidden	The authenticated user account does not have the necessary permissions for the operation.
404 Not Found	The requested resource could not be found. Check the request path and any identifiers in the request for typos.
405 Method Not Allowed	The 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 Acceptable	The request’s Accept header doesn’t permit the operation’s response format (typically application/json).
415 Unsupported Media Type	The request’s Content-Type header doesn’t match the operation’s required type (typically application/json).

Change Policy

The Forward Networks 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