PAN-OS REST API Request and Response Structure
Table of Contents
9.1 (EoL)
Expand all | Collapse all
-
- Upgrade a Firewall to the Latest PAN-OS Version (API)
- Show and Manage GlobalProtect Users (API)
- Query a Firewall from Panorama (API)
- Upgrade PAN-OS on Multiple HA Firewalls through Panorama (API)
- Automatically Check for and Install Content Updates (API)
- Enforce Policy using External Dynamic Lists and AutoFocus Artifacts (API)
- Configure SAML 2.0 Authentication (API)
-
- Asynchronous and Synchronous Requests to the PAN-OS XML API
- Run Operational Mode Commands (API)
- Apply User-ID Mapping and Populate Dynamic Groups (API)
- Get Version Info (API)
-
- PAN-OS REST API
- Access the PAN-OS REST API
- Resource Methods and Query Parameters (REST API)
- PAN-OS REST API Request and Response Structure
- PAN-OS REST API Error Codes
- Work With Objects (REST API)
- Create a Security Policy Rule (REST API)
- Work with Policy Rules on Panorama (REST API)
- Create a Tag (REST API)
- Configure a Security Zone (REST API)
- Configure an SD-WAN Interface (REST API)
- Create an SD-WAN Policy Pre Rule (REST API)
End-of-Life (EoL)
PAN-OS REST API Request and Response Structure
The PAN-OS REST API enables you to perform CRUD operations
with objects and use them in policy rules. A resource in the PAN-OS REST
API is an endpoint that you can configure with parameters. When
you make requests with the endpoints, you get responses that contain
information. The request and response formats support JSON (default)
and XML.
In PAN-OS 9.1, after you configure the firewalls and Panorama
using the REST API, you must use the XML API or the other management
interfaces to commit your changes to the running configuration.
Request Format
The API request format
is constructed as shown in the example below:
https://<IP address or FQDN of the firewall or Panorama>/restapi/<PAN-OS version>/<resource URI>?<query parameters>request body
- Base path and the resource URI for the endpoint. See Access the PAN-OS REST API for details.
- Query parameters. Every request includes query parameters that are passed to the API endpoint using query strings. The query parameters are appended to the URL with a ? that indicates the start of the query string. The query parameters appear after the ?, the parameter are concatenated with other parameters using the ampersand & symbol.
Query Parameters on the firewall - name (name) of the resource.
- location (vsys, predefined, shared, panorama-pushed) of the resource on which you want to perform the operation. A predefined object or rule is built-in to the firewall and you cannot edit, rename or delete predefined objects or policy rules.
- virtual system (vsys) name for the resource, if location is vsys or panorama-pushed.
- input format (input-format). JSON is default, or XML. You can specify an input format for HTTP methods that have a request body, such as PUT to update and POST to create a resource.
- output format (output-format) JSON default, or XML
Query Parameters on Panorama - name (name) of the resource.
- location (predefined, shared, device-group, panorama-pushed) of the resource on which you want to perform the operation. A predefined object or rule is built-in to Panorama and you cannot edit, rename or delete predefined objects or policy rules.
- device group (device-group) name of the Panorama device group to which you have assigned the firewalls, if location is device-group.
- input format (input-format). JSON is default, or XML. You can specify an input format for HTTP methods that have a request body, such as PUT to update and POST to create a resource.
- output format (output-format) JSON default, or XML
- Request body. When you create a resource with a POST request or edit a resource with a PUT request, you include a JSON or XML formatted request body in which you specify the properties for the resource you want to create or modify on the endpoint.
When
you make an API request to the firewall or Panorama, the API key
is required to authenticate the user who is making the request.
You can enter the key with the custom HTTP header X-PAN-KEY: <key>.
Learn about API Authentication and Security and
how to Get Your API Key.
Success Response Format
The HTTP response
for a successful call has three elements: status, code, and result.
The code is a numeric value. Refer to the PAN-OS XML API Error Codes for details
on the code included in the HTTP response message.
{ "@code": "19", "@status": "success", "result": { "@count": "3", "@total-count": "3", "entry": [ { "@location": "vsys", "@name": "fqdn1", "@vsys": "vsys1", "fqdn": "www.test.com" }, { "@location": "vsys", "@name": "Peer1", "@vsys": "vsys1", "ip-netmask": "172.0.0.1/24" }, { "@location": "vsys", "@name": "Peer2renamed", "@oldname": "Peer2", "@vsys": "vsys1", "ip-netmask": "200.0.0.1/24" } ] } }
Error Response Format
In addition to the
HTTP status code, the error response includes a JSON object or XML
with error information. The following is an example of an error
response body from a REST API call to get an address. In this example,
the request is missing a query parameter:
{ "code": 3, "details": [ { "@type": "CauseInfo", "causes": [ { "code": 7, "description": "Missing Query Parameter: name", "module": "panui_restapi" } ] } ], "message": "Missing Query Parameter: name" }
The following table describes the error response
fields.
Field | Description |
---|---|
code | Feature-specific error code. The codes are listed in PAN-OS REST API Error Codes |
message | Human-readable message that corresponds to the code |
details | Array of objects containing detailed data about the error |
details.@type | Type of data in details.
Currently, the only type available is CauseInfo The details under CauseInfo are for readability
and debugging purposes. The value can change between software releases.
To avoid your scripts breaking between releases, don’t parse the
values in details.causes. |
details.causes | Array of objects that convey module-level error data |
details.causes.module | Feature-specific module that reported the error |
details.causes.code | Module-level error code. If details.causes.module is panui_mgmt, then you can find this module-level code in PAN-OS REST API Error Codes |
details.causes.description | Details about the error, from the feature-specific module. |