This article describes how browser developer tools can be used to troubleshoot FortiManager API issues.
Scope
FortiManager, FortiAnalyzer.
Solution
FortiManager has extensive API support which can be leveraged for creating/modifying/deleting actions. This article shows how to approach API troubleshooting if an API is not working as expected, explore the API components – request headers, response headers, and data payloads to understand the API request/response process & troubleshoot API call failures.
Step 1: Refer to the FortiManager API documentation.
FortiManager API uses JSON API format, which enables using API calls to implement configuration changes (add/delete/modify) to the FortiManager database, as well as extract monitoring information of devices managed by FortiManager (FortGates/FortiSwitches/FortiAPs, etc).
JSON API uses JSON-RPC which is a remote procedure call protocol encoded in JSON. The link below describes the most commonly used APIs for FortiManager for various activities, for each Firmware version.
Step 2: Refer to the FortiManager API examples/templates in Postman.
There are extensive FortiManager API examples in the repository below, which can be used as templates for various actions like login/authentication, create/delete ADOMs, Firmware upgrades, policy packages, firewall objects, IPSec VPN, SD-WAN, scripts, etc.
To send API calls to FortiManager, a client program (like Postman) must first send an HTTP POST request for authentication/login to https://<fmg_ip>/jsonrpc, where <fmg_ip> is the IP address or FQDN of the FortiManager. The repository below provides several examples of such API calls for authentication, configuration changes, and monitoring activities.
Step 3: Use browser developer tools to troubleshoot if an API call is not working as expected or to explore additional APIs.
If an API call is failing to execute or not returning expected responses, it is possible to troubleshoot this using browser developer tools to compare and review what was the request header/payload that was sent by the API call from the client program (like Postman) for a particular action (say creating a firewall policy).
This can be done with what would be returned by the same action (creating the same firewall policy) from the FortiManager itself when it makes an API call on the GUI directly; compare the request/response headers & data payloads for both scenarios to understand where the issue could be. Let’s discuss this with an example below.
Here is an example of creating IPSec VPN parameters on FortiManager for a VPN tunnel using APIs, and start with creating an IPSec-phase-1 policy. For this use case, Postman, and the API example template from the repository mentioned in Step 2 are used. Start with using the template ‘FortiManager > IPSec > Create IPSec phase1‘. It is possible to add a few additional attributes as necessary to the phase 1 policy on top of what is provided in the template. In this example, the API call is failing with the below error:
The API call fails to create the IPSec policy, with a generic error ‘The data is invalid for selected url: expected -10 to equal 0’.
This could be difficult to interpret but the first step is to verify all the attributes and values in the API request header & data payload in the body, if there are any syntax errors with attribute names and values, refer to the API documentation in Step 1.
If the error can be found with the documentation, correct the syntax accordingly and re-run the API call. If the issue persists, and the syntax for a specific attribute/value cannot be found in the API documentation (note that the documentation is not exhaustive and might not contain all the attributes/values), it is possible to use the browser developer tools with the FortiManager GUI and find out what API call is used by FortiManager to do the same task directly from the GUI. This is illustrated below.
The example below is with the Chrome browser, but the logic is the same with other browsers like Firefox or Edge.
Open the FortiManager GUI and login. Then select the ‘Three-dot menu’ button to the right of the address bar, and select More Tools > Developer Tools. Next, select the ‘Network’ tab, and start the capture. Now create the IPSec phase 1 policy under VPN from the FrotiManager GUI, with the same attribute/values desired to create using API earlier (which had failed). A screenshot is shown below to illustrate the same.
Once the policy is successfully created from GUI, on the left of the developer tools panel scroll and search for the entry that corresponds to the action that created the IPSec phase 1 policy, as shown in the example above. Once this is located, select the ‘Payload’ tab, and expand the data section.
This contains all the standard/correct syntaxes of the attribute/value pairs with which the policy was successfully created using GUI, and can be used as a reference for the API calls. There will be many attribute/value pairs here (many of them are optional and default settings), but specifically look for the ones used in the API earlier.
Compare this with the syntax of the attributes & values in the API’s request body section and see if any corrections are needed. In the API example below observe the syntax of the local id attribute:
It is possible to see the syntax of the local id attribute is incorrect in the API call, as per the FortiManager GUI API call it should be ‘localid’ but in the API call it is ‘local-id’. Let’s correct this syntax and retry running the API call:
There is now the API call successfully executed, and the IPSec phase 1 policy created in the FortiManager. This was an illustration of using Developer tools on a browser to troubleshoot such FortiManager API issues, and can also be used to explore other APIs of interest by reviewing the API calls made by FortiManager GUI.
Note: Always test the APIs first on lab devices or a staging setup, before implementing it for production devices.