How to Get the Most Out of Big Network's REST API

Tom Daly
March 21, 2023
Unlock the full potential of Big Network's REST API. This guide provides insights into API key management, making API requests, error handling, and more. Learn how to create complex network topologies and manage edge devices with our API.

Big Network's REST API is a powerful tool that allows developers to efficiently interact with cloud network resources and manage edge devices in a streamlined manner. By leveraging the API, developers can create complex network topologies, automate tasks, and build custom applications to meet their organization’s unique needs. It provides a single, unified interface for accessing and controlling various cloud networks and edge devices that make up the network topology desired by a customer.

Background: What is an API?

API Definition

An Application Programming Interface (API) allows for machine-to-machine communication between systems. APIs are used both externally between and internally among organizations. Common API frameworks include Simple Object Access Protocol (SOAP), GraphQL, and gRPC (Remote Procedure Call). All of these frameworks create a contract between a client and server so that everyone is talking a common language.

At Big Network, we have created a REST API. It uses standard HTTP methods like GET, POST, PUT, and DELETE to perform operations via the API. Responses from the API use standard HTTP status codes to communicate success, failure, or other conditions, and responses are returned in Javascript Object Notation (JSON) format.

The API is designed to be secure, with key features including API key management and access rate limiting. API key management is simple and straightforward, allowing users to generate, rotate, and revoke API keys as needed through the Big Network Portal. Rate limiting has been deployed to prevent our API systems from being overwhelmed with a flood of requests (should this situation occur). In the event that your key is suspended, you can contact Big Network's Support Team for assistance and to have the suspension lifted.

API Specification

We have also built a complete specification to our API. Developers seeking to understand exactly how to interact with our API, or try various examples, can access our API documentation or OpenAPI specification. The OpenAPI specification is useful in cases where developers want to use various code generation tools to create software bindings into the Big Network APIs.


To get a better understanding of the API and familiarize yourself with its capabilities, you can send test requests directly from the API documentation page. This can help you test the API and evaluate its functionality before incorporating it into your own applications. By prototyping and testing API requests, you can gain a deeper understanding of the API and ensure that it will meet your needs and requirements.

With all of this in mind, let’s talk about API Key Management so you can get started in using Big Network’s API.

Getting Started: Generate an API Key

To get started with Big Network's API, you need to obtain an API key. This key is required for authentication and authorization of each API request. The Big Network Portal offers full API key management, making it simple to obtain, rotate, and revoke API keys as needed. To obtain an API key, you need to navigate to the Big Network Portal. From there, go to the Organization section, then to API. You can then generate your API key by clicking on the "Generate" button. It is important to store your API key in a secure location and not share it with others. The scope of API keys are unique to the intersection of a user and an organization. The same permissions apply to a generated API key as the user has on their current account. Changing your account permissions by organization administrators will result in a change of API key permissions.

Create new API Key

Making API Requests

Big Network's API is a RESTful API that supports multiple request types (GET, POST, PATCH, DELETE). The API tells you if a request was successful or not by using HTTP status codes. To make API requests, you will need to include the following components:

  • API Key Header: Include the following header in every request to authenticate and authorize: "api-key: << generated key >>"
  • Endpoint: the specific endpoint you are trying to access (e.g. /v1/organizations, /v1/organization/{orgID}/networks, /v1/organization/{orgID}/edge-devices/, etc.)
  • Query parameters: any additional parameters you want to pass in your request (e.g. search terms, date range)

For example, list all Edge Devices in your organization using cURL and JQ (for formatting):

username@MacBook-Pro ~ % curl -s -H "api-key: <key>"<orgID>/edge-devices | jq '.[].name' | sort
"210L OOB #1"
"210L OOB #2"
"210L edge-01-210L"
"210L edge-02-210L"
"30T Server Room"
"5J Console Server"
"5J Server Room"
"edge-01-bos on transit-01-bos"

Error Handling

The API uses HTTP status codes to communicate success or failure of a request, with 2xx status codes indicating success and 4xx or 5xx status codes indicating an error. When an error occurs, the API returns the appropriate HTTP status code, along with a descriptive error message. This helps developers understand what went wrong with the request and take necessary steps to resolve the issue.

It is important to handle these errors in your code to ensure a seamless user experience for end-users. Implementing proper error handling helps minimize disruptions and prevents issues from impacting the overall performance of your application.


Big Network offers a REST API that provides a simple and unified interface for developers to program cloud networks and edge devices. With our API, developers can create complex network topologies, manage edge devices, and interact with cloud resources. Additionally, Big Network provides full support for API key management, making it easy for developers to generate, rotate, and revoke API keys as needed. In case of errors, the API returns descriptive error messages along with an HTTP status code to ensure a smooth experience for end-users.

To get the full Big Network API support guide, head to our Knowledge Base to access the article.

Ready to Network? 
Schedule a DemoHow to buy