Quick start
Connect to a FortiGate and read, change and create objects.
Quick start
Create a REST API administrator on the FortiGate, point forti-api at it, and read, change and create objects.
Connect and make your first calls
1 Create an API administrator
On the FortiGate, create a REST API administrator (System, Administrators, Create New, REST API Admin), give it an access profile with the permissions you need, restrict its trusted hosts to the machines that will call the API, and copy the generated API key.
2 Configure the connection
The default client reads its configuration from the environment:
1export FORTIGATE_HOST=fortigate.example.com2export FORTIGATE_ADMIN_HTTPS_PORT=4433export FORTIGATE_API_KEY=...See Configuration for every variable, or configure a client in code:
1#include <forti_api.hpp>2 3fortiapi::Config config;4config.host = "fortigate.example.com";5config.port = 8443;6config.api_key = api_key;7fortiapi::set_default_client(std::make_shared<fortiapi::Client>(config));3 Read, change, create
1#include <forti_api/firewall.hpp>2#include <iostream>3 4using namespace fortiapi;5 6int main() try {7 for (const auto& policy: firewall::Policies::list(Query().filter("status==enable")))8 std::cout << *policy.policyid << " " << policy.name.value_or("") << "\n";9 10 auto address = firewall::Addresses::get("LAN 10.0.0.0/24");11 address.comment = "managed by forti-api";12 firewall::Addresses::update(address);13 14 firewall::Address host;15 host.name = "printer";16 host.subnet = "192.168.1.50 255.255.255.255";17 firewall::Addresses::add(host);18} catch (const fortiapi::Error& error) {19 std::cerr << error.what() << "\n";20 return 1;21}
If requests keep failing to authenticate, stop and fix the key or trusted hosts: FortiOS locks the API out (HTTP 429) after repeated authentication failures, and forti-api never retries HTTP 401.
Endpoint operations
Each generated endpoint is a Table (objects addressed by a key) or a Singleton (an object that
exists exactly once, such as system/global):
| Operation | Table | Singleton | Result |
|---|---|---|---|
list(query) | yes | every object, decoded | |
find(key, query) | yes | the object, or std::nullopt when it does not exist | |
get(key, query) / get(query) | yes | yes | the object; a Table throws ApiError (not_found()) when it does not exist |
contains(key, query) | yes | whether the object exists | |
add(object, query) | yes | creates the object; see Fields and updates | |
update(object, query) | yes | yes | sends only modified and cleared attributes; std::nullopt when there is nothing to send |
del(key, query) | yes | deletes the object | |
schema() | yes | yes | the endpoint's FortiOS schema (?action=schema) |
Several devices
Every call accepts an optional Query and Client as trailing arguments, so the same code works
against several devices:
1fortiapi::Client branch(branch_config);2auto policies = firewall::Policies::list({}, branch);The repository's examples/inventory.cpp is a complete read-only program.