API v2 Overview
APIv2 is ProVision's currently supported RESTful API version. APIv2 adds new endpoints and upgraded functionality over APIv1, through use of HTTPS authentication, additional HTTP methods (GET, PUT, POST, etc.), and JSON payloads.
To test APIv2 queries, you may:
-
Use a browser extension REST client, such as Postman
-
Access ProVision's APIv2 Swagger documentation from your ProVision instance ( instance/dev/swagger), which provides the ability to test inputs and responses using your ProVision instance data.
APIv2 Swagger Documentation
Accessing Swagger
Public APIv2 documentation is located here.
APIv2 documentation includes:
-
IPAM API: Includes actions for LIRs, IP aggregate and block management, VLAN, IP Rules, and SWIP.
-
Resource API: Includes actions for managing the ProVision Resource System. The resource API provides CRUD endpoints for resources, resource attributes, resource attachments and resource backups.
-
DNS API: ProVision DNS API allows you to manage DNS Zones, Records, Servers, Groups and ACLS.
-
Users API: Includes actions for ProVision Users, permissions and actions.
-
Usergroups API: Includes actions for ProVision Groups, permissions and actions
-
Scheduler API: The API Allows you to easily schedule tasks.
-
API Composer Platform (ACP): ACP is an additional module in ProVision to help automate frequently used combinations of calls.
Existing customers may access APIv2 documentation from your ProVision instance (user must have Admin permissions):
-
Log into your ProVision instance.
-
Go to the Admin area of ProVision and click on the API Tab.
-
Under "OpenAPI 3.0 Specification" click the Swagger link provided.
Viewing APIv2 Information
-
On the Provision API Swagger home page, click on the name link for the API family that you wish to browse (IPAM, Resource, DNS, etc).
Click to expand...
-
Once on an API Family page, verify that the displayed server name is correct for your instance/local server.
Click to expand...
In most situations, only one ProVision instance/server will be displayed, with authentication already provided from your ProVision login. If your ProVision session has ended, or the server changed, you may need to re-provide ProVision credentials by clicking the "Authorize" button.
-
Scroll further down the page and begin reviewing available APIv2 calls and details. Clicking on any call will expand it to view parameter details - you can even test call responses (using your instance data) by clicking "Try it Out"!
Click to expand...
The detail information includes a description, parameter list (required parameters are marked with a *), and response information
-
Some calls that involve a JSON request body payload (PUT, PATCH, etc) will display "Example Value" and "Model" information under a "Request Body" section - additional parameter descriptions may be displayed under "Model" Information.
Click to expand...
Clicking on "Example Value" will show an example of a JSON request body for that call.
Clicking on "Model" will display details and descriptions of the request body parameters, if available.
-
Additional "Model" examples are available at the bottom of the page with additional descriptive information.
Click to expand...
At the bottom of the page, click on "Models".
Then, click on the "Model" you wish to view. Some models may contain additional information that you can expand to view, such as valid values for a parameter. In the example below, the circled "array" will display valid RIR values.
Testing Endpoints
You may test queries in Swagger by using the "Try it out" button for any call.
-
Navigate to the call that you want to try out.
-
Expand the call to view its details, then click the "Try it out" button.
-
Input the desired parameters to test, and click "Execute".
Click to expand...
If the call is a method that uses a JSON request body, you will have the option to edit the body text in the "Example Value" box - when done, click "Execute".
-
The example response will display under "Responses" after being executed.
Click to expand...
