APIv2

Image Added

API v2 Overview

APIv2 is ProVision's currently supported RESTful API version. APIv2 improvements include: 

• HTTP HTTPS Basic Authentication
• Use of HTTP Methods (GET, PUT, POST, etc.)
• Supports JSON payloads
• Additional endpoints and ProVision functionalityand functionality

APIv2 Access Options

To test or execute APIv2 queries, you may:

1. Use a browser extension / desktop REST client, such as Postman

   1. Postman is the current industry standard: Go to https://www.getpostman.com/ to install, and visit the Postman Learning Center for user documentation, training videos, and support help.

2. Access ProVision's APIv2 the APIv2 Swagger documentation from your ProVision instance (   instance/dev/swagger), which provides the ability to test inputs and responses using your ProVision instance data.
   1. Continue to the section below: "APIv2 - Using Swagger" for more details, or see the ProVision Developer Tools page for a broader overview.
3. Use CURL in the command line to authenticate and execute APIv2 endpoints. See cURL documentation at https://curl.haxx.se/.
   1. Continue to the section below: "APIv2 - Using cURL" for more details, examples, and tips.

...

Public APIv2 documentation is located at https://cloud.6connect.com/APIv2/. 

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 Resource System. 
The resource API provides CRUD endpoints for resources, resource attributes, resource attachments and resource backups.

• Resource View API

Provides CRUD endpoints for resource views.

• DNS APIProVision

The DNS API allows you to manage DNS Zones, Records, Servers, Groups and ACLS.

• Peering API

Allows you to manage routers and BGP sessions.

• Contacts API

Allows you to manage contacts.

• Users API

Includes actions for

...

Users, permissions and actions.

• Usergroups API

Includes actions for

...

Groups, permissions and actions

• Scheduler API

The API Allows you to easily schedule tasks.

• API Composer Platform

API Composer Platform (ACP) is an additional module

...

to help automate frequently used combinations of calls.

• SSH API

Includes actions for SSH credentials and SHH Routes. 

Existing customers may also access APIv2 documentation Documentation from your ProVision instance (user must have Admin permissions):

1. Log into your ProVision instance.
2. Go to the Admin area of ProVision and click on the the API Tab Tab.

3. Under "OpenAPI 3.0 Specification" click the Swagger link providedthe API dropdown menu, click the Swagger link provided. You may also click on the "APIv2 Swagger Documentation" link provided under the APIv2 section of the page.

   Expand
   Image RemovedImage Added

   
   

Viewing APIv2 Information

1. On the 6connect Provision API Swagger home page, click on the name link for the API family that you wish to browse (IPAM, Resource, DNS, etc).

   Expand
   Image RemovedImage Added

   
   

2. Once on an API Family page, verify that the displayed server name is correct for your instance/local server. 

   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.

   
   

3. 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"!

   Expand
   The detail information includes a description, parameter list (required parameters are marked with a *), and response information

   
   

4. 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. 

   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.

   
   

5. Additional "Model" examples are available at the bottom of the page with additional descriptive information. 

   Expand
   At the bottom of the page, click on "Models". Image Modified 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. Image Modified

   
   

Testing/Executing Endpoints in Swagger

...

1.  Navigate to the call that you want to try out.

2.  Expand the call to view its details, then click the "Try it out" button.

   Expand

   
   

3. Input the desired parameters to test, and click "Execute".

   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".

   
   

4. The example response will display under "Responses" after being executed. The "Response" section also includes the cURL command, Request URL, and Response Headers.

   Image Removed

   Expand
   Image Added

   
   

APIv2 - Nested Queries

You can use nesting to write more complicated API calls to handle multiple conditions. Here, we'll  illustrate a query with an OR / AND condition, such as to find resource entries with (Section = 76 OR Section = 77) AND managed = Yes:

{"type": "entry","attrs":[{"key":"_custom_id","value":"101","rule":"AND"},{"attr_rule":"AND","attr_nested":[{"attr_key":"_section","attr_value":"78","attr_rule":"OR"},{"attr_key":"_section","attr_value":"74","attr_rule":"OR"}]}]}

You should be able to adapt that to point at whatever attributes you like. 

Here it is in CURL format:

curl -X POST "https://$HOSTNAME/instance/api/v2/resources/query" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"entry\",\"attrs\":[{\"key\":\"_custom_id\",\"value\":\"101\",\"rule\":\"AND\"},{\"attr_rule\":\"AND\",\"attr_nested\":[{\"attr_key\":\"_section\",\"attr_value\":\"78\",\"attr_rule\":\"OR\"},{\"attr_key\":\"_section\",\"attr_value\":\"74\",\"attr_rule\":\"OR\"}]}]}"

APIv2 - Using cURL

One option to execute an APIv2 call is to use CURL from the Command Line.

...

1. Invoke cURL:

   1. curl -X PATCH "https://your-instance-domain$HOSTNAME/instance-name/api/v2/config" -H "Content-Type:application/json;charset=utf-8" -u testing@6connecttesting@example.com:password -d "{\"auto_merge_limits\":\"10\"}"

2. Use the Request Flag (-X):

   1. curl -X PATCH "https://your-instance-domain$HOSTNAME/instance-name/api/v2/config" -H "Content-Type:application/json;charset=utf-8" -u testing@6connecttesting@example.com:password -d "{\"auto_merge_limits\":\"10\"}"

   2. This specifies a custom request method to use when communicating with the HTTP server. The specified request method will be used instead of the method otherwise used (which defaults to GET)
3. Specify the HTTP Action:

1. curl -X PATCH "https://your-instance-domain$HOSTNAME/instance-name/api/v2/config" -H "Content-Type:application/json;charset=utf-8" -u testing@6connecttesting@example.com:password -d "{\"auto_merge_limits\":\"10\"}"

4. In quotes, specify the URL of the APIv2 endpoint you are executing. This should be similar to: "https://[ProVisionInstance]$HOSTNAME/instance/api/v2/[endpoint family-action]"

   1. curl -X PATCH "https://https:$HOSTNAME//your-instance-domain/instance-name/api/v2/config" -H "Content-Type:application/json;charset=utf-8" -u testing@6connecttesting@example.com:password -d "{\"auto_merge_limits\":\"10\"}"

5. Use the Header Flag (-H):

   1. curl -X PATCH "https://https:$HOSTNAME//your-instance-domain/instance-name/api/v2/config" -H "Content-Type:application/json;charset=utf-8" -u testing@6connecttesting@example.com:password -d "{\"auto_merge_limits\":\"10\"}"

   2. Denotes an extra header to include in the request when sending HTTP to a server. You may specify any number of extra headers. Note that if you should add a custom header that has the same name as one of the internal ones curl would use, your externally set header will be used instead of the internal one. This allows you to make even trickier stuff than curl would normally do. 
6. Add endpoint-specific data, such as specifying a JSON payload or attribute setting. This may involve one or more additional flags or information sets, depending on the endpoint:

   1. curl -X PATCH "https://https:$HOSTNAME//your-instance-domain/instance-name/api/v2/config" -H "Content-Type:application/json;charset=utf-8" -u testing@6connecttesting@example.com:password -d "{\"auto_merge_limits\":\"10\"}"

...

cURL Examples

...

This example authenticates a ProVision user, so that you may perform APIv2 commands as that user.

curl -X GET "https://2-dev.6connect.com/qa-7.3.0$HOSTNAME/instance/api/v2/config" -H "accept: */*" -u testing@6connecttesting@example.com

This will ask for a password.  To hard-code it with a password, add it to the end like so:

...

curl -X GET "https://2-dev.6connect.com/qa-7.3.0$HOSTNAME/instance/api/v2/config" -H "accept: */*" -u testing@6connecttesting@example.com:password

APIv2 commands are executed as the user provided, so their permissions must be set appropriately.  The Swagger "execute" feature produces CURL strings that can be used to test specific API commands.

...

This example illustrates how to provide POST/PATCH data to an APIv2 command via cURL.  This command updates the ProVision automerge the automerge configuration setting:

curl -X PATCH "https://2-dev.6connect.com/qa-7.3.0$HOSTNAME/instance/api/v2/config" -H "Content-Type:application/json;charset=utf-8" -u testing@6connecttesting@example.com:password -d "{\"auto_merge_limits\":\"10\"}"

Review the general CURL documentation at https://curl.haxx.se/ can offer greater insight into what other flags can be used. 

Example: cURL / APIv2 Nested Query

You can use nesting to write more complicated API calls to handle multiple conditions. Here, we'll  illustrate a query with an OR / AND condition, such as to find resource entries with (Section = 76 OR Section = 77) AND managed = Yes:

{"type": "entry","attrs":[{"key":"_custom_id","value":"101","rule":"AND"},{"attr_rule":"AND","attr_nested":[{"attr_key":"_section","attr_value":"78","attr_rule":"OR"},{"attr_key":"_section","attr_value":"74","attr_rule":"OR"}]}]}

The items in bold red are the necessary components to achieve the AND/OR condition in a nested format, though the attributes used may be changed depending on your needs. 

The same query in cURL is given below:

curl -X POST "https://$HOSTNAME/instance/api/v2/resources/query" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"entry\",\"attrs\":[{\"key\":\"_custom_id\",\"value\":\"101\",\"rule\":\"AND\"},{\"attr_rule\":\"AND\",\"attr_nested\":[{\"attr_key\":\"_section\",\"attr_value\":\"78\",\"attr_rule\":\"OR\"},{\"attr_key\":\"_section\",\"attr_value\":\"74\",\"attr_rule\":\"OR\"}]}]}"

Example: cURL APIv2 Attach Zone to a DNS Group

To attach a newly created DNS Zone to a DNS Group using APIv2, you need to make a Resource Link with the relation type "dnsZoneView":

curl -X POST "https://$HOSTNAME/instance/api/v2/resources/274/links" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"resource_id\":\"15648\",\"relation\":\"dnsZoneView\",\"data\":{}}"

Where resource #274 is the "Default Group" on the instance (your instance may vary), and Resource #15648 is the resource ID for the new zone.  The two are now linked together. 

To attach a DNS server to a DNS Group you use the same process but the relation is "dnsViewServer". 

To attach a zone to a server directly the relation is either "dnsZoneMaster" or "dnsZoneSlave" depending on what you're doing.

Additional Information

See the following areas for additional information:

• ProVision Developer Tools
• Public APIv2 Swagger documentation:  https://cloud.6connect.com/APIv2/.