Before sending requests to the Batfish REST API, consider the following steps to ensure secure and proper access:

1. Determine Authentication Requirements: By default, Batfish runs without authentication enabled. Check whether your deployment has authentication configured (for example, in shared or production environments).
2. Review Authentication Configuration: If authentication is enabled, Batfish typically supports integration with third-party providers using standards like OIDC (OpenID Connect). This is managed through configuration files supplied to the server at startup.
3. Obtain Access Credentials: Secure any necessary credentials or tokens as required by your deployment’s authentication method. This may involve authenticating against an identity provider or obtaining access tokens.
4. Include Authorization Details in Requests: When authentication is active, add the proper Authorization header or token to your HTTP requests. For example:

   Authorization: Bearer <your-access-token>
       

5. Use Secure Channels: Always communicate with the Batfish REST API over HTTPS, especially if authentication is required, to protect your credentials and data in transit.
6. Verify Access on Each Request: If authentication is enabled, the API will reject unauthenticated or invalid requests with an appropriate error (such as HTTP 401 or 403). Double check your credentials or token if you receive such errors.

Consult your team's or organization's policies for additional authentication or access control requirements specific to your environment.

This section describes how to interact with the most frequently used Batfish REST API endpoints, guiding you step by step through typical network analysis workflows:

1. Create or Select a Network:
   Use this endpoint to create a new logical environment for your analysis.

   POST /networks

   Payload Example:

   {
     "name": "sample_network"
   }
       

2. Upload a Snapshot:
   This endpoint is used to upload device configurations and network state for analysis.

   POST /networks/<network>/snapshots?snapshot=<snapshot_name>

   Payload: Multipart form-data containing your configuration files.
3. List Available Networks or Snapshots:
   Retrieve a list of your networks or available snapshots.

   GET /networks

   GET /networks/<network>/snapshots

4. List Available Questions:
   View which analysis questions can be executed against your snapshot.

   GET /questions

5. Execute a Question:
   Run a specific network analysis against your uploaded snapshot.

   POST /networks/<network>/snapshots/<snapshot>/questions/<question>

   Payload Example:

   {
     "parameters": { }
   }
       

6. Retrieve Question Results:
   Fetch the results of your analysis.

   GET /networks/<network>/snapshots/<snapshot>/questions/<question>/answer

7. Delete a Network or Snapshot (Optional):
   Remove outdated resources.

   DELETE /networks/<network>

   DELETE /networks/<network>/snapshots/<snapshot>

Replace <network>, <snapshot>, and <question> with your own network, snapshot names, and desired question type. All endpoints accept and return JSON unless uploading a snapshot, which uses multipart form data.

This section guides you through a typical workflow for using the Batfish REST API to automate network analysis tasks, step by step:

1. Create a Network:
   Start by creating a new network environment to organize your snapshots and analyses.

   POST /networks
   Content-Type: application/json
   
   {
     "name": "my_network"
   }
       

2. Upload a Snapshot:
   Next, upload your network configuration files as a snapshot. This provides Batfish the data needed for analysis.

   POST /networks/my_network/snapshots?snapshot=my_snapshot
   Content-Type: multipart/form-data
   
   [Include device config files here]
       

3. List Available Questions:
   Before running an analysis, check which questions (analysis types) you can execute.

   GET /questions
       

4. Execute a Question:
   Run a specific analysis query on your snapshot to gather network insights.

   POST /networks/my_network/snapshots/my_snapshot/questions/init_info
   Content-Type: application/json
   
   {
     "parameters": {}
   }
       

5. Retrieve the Answer:
   Obtain the results of your question execution to review findings.

   GET /networks/my_network/snapshots/my_snapshot/questions/init_info/answer
       

This workflow demonstrates a common pattern for integrating Batfish REST API calls into automation or validation scripts. Adjust the network, snapshot, and question names as needed for your environment.

This section explains the data formats expected and returned when interacting with the Batfish REST API, with step-by-step details:

1. JSON Format for Requests and Responses:
   Most Batfish REST API endpoints accept and return data formatted as JSON. Ensure your request bodies are properly structured JSON objects or arrays.

   {
     "parameters": {
       "someParameter": "value"
     }
   }
       

2. Multipart Form-Data for Snapshot Uploads:
   When uploading snapshots, the API requires a multipart form-data payload containing your device configuration files. Each file should be included as a separate part.

   Content-Type: multipart/form-data; boundary=------------------------xyz
   
   --------------------------xyz
   Content-Disposition: form-data; name="file"; filename="config1.cfg"
   Content-Type: text/plain
   
   [contents of config1.cfg]
   
   --------------------------xyz
   Content-Disposition: form-data; name="file"; filename="config2.cfg"
   Content-Type: text/plain
   
   [contents of config2.cfg]
   
   --------------------------xyz--
       

3. Ensure Proper Content-Type Headers:
   Set the Content-Type header appropriately for each request:
   • Use application/json for JSON payloads
   • Use multipart/form-data and specify the boundary when uploading files
4. Validate JSON Syntax:
   Before sending requests, verify your JSON is valid using a linter or formatter to avoid request errors.
5. Response Data:
   API responses will generally be JSON objects. Parse them accordingly in your automation or scripts to extract needed information.

Following these payload format guidelines ensures smooth communication with the Batfish REST API and reduces errors during automation and integration workflows.

This section walks you through the typical HTTP response codes you may encounter while working with the Batfish REST API and what they indicate at each step:

1. 200 OK:
   The request was successful and the response contains the expected data. Common for retrieval, execution, and status-check endpoints.
2. 201 Created:
   A resource (such as a new network or snapshot) was successfully created. The response may include information about the new resource.
3. 400 Bad Request:
   The server could not process the request due to invalid syntax or data. Check the request body for errors or missing fields.
4. 401 Unauthorized:
   The request lacks valid authentication credentials. Confirm that you have the right token or authorization headers if authentication is enabled.
5. 403 Forbidden:
   Authentication succeeded but you do not have sufficient permissions to perform the action.
6. 404 Not Found:
   The requested resource does not exist. Double-check network, snapshot, or question names in the URL.
7. 500 Internal Server Error:
   An unexpected problem occurred on the server side. If this error persists, review server logs or reach out for support.

Properly handling these response codes can help you quickly detect issues and ensure robust interaction with the Batfish REST API during automation or troubleshooting.