| Description | 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 describes how to approach API troubleshooting if an API call is not working as expected. It will explore the FortiManager API components - request headers, response headers, and data payloads with examples to understand the API request/response flow and 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.
FortiManager API documentation on the Fortinet Developer Network.
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.
FortiManager public API repository: Postman FortiManager.
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), with what is returned by the same action (creating the same firewall policy) from the FortiManager itself on the GUI directly (which also sends an API call). Compare the request/response headers & data payloads for both these scenarios to understand where the issue could be. Let's discuss this with an example below.
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), browser developer tools can be used 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 web browser, but the logic is the same with other web 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 that were used in the API call earlier (which had failed). A screenshot is shown below to illustrate the same.
Once the policy is successfully created from the GUI, scroll on the left of the developer tools panel to 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), but specifically look for the ones used in the API earlier.
Compare this with the syntax of the attributes & values in the Postman 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:
As seen in the above screenshot, the syntax of the local ID attribute is incorrect in the Postman API call, since as per the FortiManager GUI API call it should be 'localid' but in the Postman API call it is 'local-id'. Let's correct this syntax and retry running the API call:
The API call is now successfully executed, and the IPSec phase 1 policy is 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 for various actions.
Note: Always test the APIs first on lab devices or a staging setup, before implementing it for production devices.
Related documents: |
