Getting Started with the Public API
Authentication
When exercising the API in Swagger UI, users can authenticate using their IO user ID and password credentials.
To access the API from another application, such as cURL or Postman, users must authenticate using a bearer token in an authorization header that is sent as part of each request. Refer to the IO Administrator Guide for information about generating API tokens. The following is an example of an authorization header: authorization: bearer MmQyYWYzMzdhNjY4YWNkYzpvU1laUTNQSDF5Vkk= . The long hash after bearer as shown above is a sample token generated by IO.
Note
Only users with IO-admin privilege can generate a token from the UI for a specific timeframe. This token grants access to the API for anyone with the token while it is valid.
Accessing Endpoint Documentation
There are two methods for accessing API endpoint documentation. The first is via the Swagger UI. The second is to specify a help query parameter to specific endpoints.
Accessing Endpoint Documentation via the Swagger UI
Note
Swagger documentation is only available directly from IO for releases 7.1.0 and higher.
After authenticating with IO, you can access the Swagger UI using the following URL, replacing IPADDRESS with the IP address or FQDN of your IO Appliance or Virtual Edition instance.
https://IPADDRESS/api/sdk/p/index.html
You can access the Swagger Documentation from the UI by navigating to User Name > API Documentation.
You'll see a page that looks like the following.
A few things to note:
In the upper left-hand corner of the page there is a link that you can click on to retrieve the OpenAPI YAML file, which can be used in third-party applications like Postman.
On the middle right-hand side of the page there is an Authorize button, which you can click on to input an API token. As you are already authenticated with IO, this is an optional step.
Beginning in the bottom two thirds of the page there are endpoint definitions. Clicking on the down arrow at the right side of each endpoint definition will reveal detailed information about that specific endpoint. Note in particular the endpoints under the Getting Started heading. Explore these endpoints first to get familiar with the API before exploring others.
The Swagger UI is interactive, allowing the user to try out various endpoints.
Accessing Endpoint Documentation Using the Help Query Parameter
You can access additional help information for each information using the help URL query parameter. Enter the following URL for a summary of supported endpoints.
https://[IP]/api/sdk/p/2/inventory?help=true
Each link contains more detailed help for each of the listed endpoints and also a list of hierarchically related endpoints. For example, the URL
https://IPADDRESS/api/sdk/p/2/inventory?help
will display information about the inventory endpoint as shown below.
Endpoint Definitions
There are currently eleven, top-level endpoints. They are:
Other related endpoints, or aliases, resolve to these top-level endpoints. For example, the aliases related to /api/sdk/p/2/schema are:
For the aliased endpoints, there's a URL parameter called "example" which, when included in the URL--it can either be empty (no value) or set to true, will return JSON information containing the URL and payload of the related top-level endpoint.
Examples
Each endpoint has examples of common use cases in the Request Body section as shown below. Selecting an example from the drop-down menu will show representative sample JSON payload for that example.
Warning
Case matters when specifying endpoint URLs and payload. In particular, IO display labels and properties must be written using the proper case or no results will be shown.
Rate Limiting and Performance
Rate limiting is applied to every endpoint as part of each request. For more specific information about these limits and their performance implications, please consult the Swagger documentation.