Resources
Warning |
---|
ProVision's APIv1 system has been replaced by APIv2, and is now considered deprecated. |
Table of Contents |
---|
get | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
URL | /api/v1/api.php?target=resource&action=get | |||||||||||||||||||||||||||
Description | Get a resource or resources | |||||||||||||||||||||||||||
Returns | Examples: SUCCESSFUL: {"success":1,"message":"Search successful","data":[{"id":"57","name":"2nd Email","slug":"6c-contact-email2","type":"field","parent_id":"1","category_id":null,"attr":[]}]} ERROR: {"success":0,"message":"Search failed"} | |||||||||||||||||||||||||||
Optional Parameters | General Parameters:
Limit Results by ID: |
HTML |
---|
<div id="google_translate_element"></div>
<script type="text/javascript">
function googleTranslateElementInit() {
new google.translate.TranslateElement({pageLanguage: 'en'}, 'google_translate_element');
}
</script>
<script type="text/javascript" src="//translate.google.com/translate_a/element.js?cb=googleTranslateElementInit"></script> |
Table of Contents |
---|
Resources
get | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
URL | /api/v1/api.php?target=resource&action=get | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Description | Get a resource or resources | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Returns | Examples: SUCCESSFUL: {"success":1,"message":"Search successful","data":[{"id":"57","name":"2nd Email","slug":"6c-contact-email2","type":"field","parent_id":"1","category_id":null,"attr":[]}]} ERROR: {"success":0,"message":"Search failed"} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Optional Parameters |
At most, one of the following:
At most, one of the following:
At most, one of the following:
You can set the order of the results by setting the STRING value of the parameter orderby to one of the following :
You can set the direction of the ordering of the results by setting the STRING value of the parameter order to one of the following :
You can further limit the results based on attributes the resources may have:
You can search on multiple attributes by including an array of attribute options: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Name | Type | Notes/Example | attributes | ARRAY |
Name | Type | Notes/Example | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
resource_link_type | STRING | The resource linkage relation name. Valid values include: For type = dnsmodule:
| ||||||||||||||
resource_link_column | INTEGER | The column to be used for the parameter in "resource_link_value". Valid integer values are: '1' = to use resource1 in the first column '2' = to use resource2 in the second column | ||||||||||||||
resource_link_value | INTEGER | The resource id for the resource_linkage table to search (Example: "10697") |
Limit Results by Attributes:
You can further limit the results based on attributes the resources may have:
Name | Type | Notes/Example |
---|---|---|
attributes | ARRAY | You can search on multiple attributes by including an array of attribute options: var data = { "type: "entry", "attributes": [ |
|
{ "attr_key": "_section", "attr_value": "105", }, { "attr_key": "address-mail-state", "attr_value": "CA", } ], "resources_per_page: 10 } |
You can restrict the range of the resources returned.
Name | Type | Notes/Example |
---|---|---|
resources_per_page | INTEGER | How many resources to return. |
offset | INTEGER | How many resources to offset (the initial resource is 0, not 1). |
paged | INTEGER | The page to return (starts at 1, not 0). This parameter is provided for convenience and is used to calculate the offset where: offset=(paged-1)*resources_per_page |
add
attr_key | STRING | The name of the attribute. Example: network-fqdn | ||
attr_value | STRING | The value of any attribute, or if attr_key is specified, the value of the attribute defined in attr_key. | ||
attr_compare | STRING | If both attr_key and attr_value are given, the results are by default compared based on the value given as attr_value being equal to the value stored in the database. You can optionally change this by setting the STRING value of attr_compare to one of the following:
| ||
attr_load | BOOL | Load resource attributes along with the resource entry |
Result Ordering:
Name | Type | Notes/Example |
---|---|---|
order | STRING | Set the direction of the ordering of the results by ascending or descending order. Valid values are:
|
orderby | STRING | The parameter to order results by. Valid values include:
|
Range Selection / Paging:
You can restrict the range of the resources returned.
Name | Type | Notes/Example |
---|---|---|
resources_per_page | INTEGER | How many resources to return per page, e.g.: '10' . |
offset | INTEGER | How many resources to offset from the initial resource, to use as the first resource provided in the return list (the initial resource is 0, not 1). |
paged | INTEGER | The page to return (starts at 1, not 0). This parameter is provided for convenience and is used to calculate the offset where: offset=(paged-1)*resources_per_page |
Examples:
/api/v1/api.php?target=resource&action=add&meta[name]=apitest&meta[type]=entry&meta[section]=firewall&fields[network-fqdn][]=www.example.com
SUCCESSFUL: {"success":1,"message":"Resource added","data":{"id":1077,"name":"apitest","slug":"apitest","type":"entry","parent_id":1,"category_id":"NULL","attr":{"_section":"70","network-fqdn":"www.example.com"},"section":{"id":"70","name":"Firewall","slug":"firewall","type":"section","parent_id":"1","category_id":null,"attr":{}}}}add | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
URL | /api/v1/api.php?target=resource&action=add | |||||||||
Description | Add a resource. | |||||||||
Returns | Examples: /api/v1/api.php?target=resource&action=add&meta[name]=apitest&meta[type]=entry&meta[section]=firewalladd&meta[name]=apitest&meta[type]=entry&fields[network-fqdn][]=www.example.com ERRORSUCCESSFUL: {"success":01,"message":"Entries must be assigned to a section"} | |||||||||
Required Parameters |
| |||||||||
Optional Parameters |
| Required Parameters (meta[type] = entry) |
Name | Type | Notes/Example |
---|---|---|
meta[section_id] | INTEGER | ID of the section that the entry will be assigned to |
meta[section] | STRING | Slug of the section that the entry will be assigned to |
Resource added","data":{"id":1077,"name":"apitest","slug":"apitest","type":"entry","parent_id":1,"category_id":"NULL","attr":{"_section":"70","network-fqdn":"www.example.com"},"section":{"id":"70","name":"Firewall","slug":"firewall","type":"section","parent_id":"1","category_id":null,"attr":{}}}}
/api/v1/api.php?target=resource&action=add&meta[name]=apitest&meta[type]=entry&fields[network-fqdn][]=www.example.com
ERROR:{"success":0,"message":"Entries must be assigned to a section"}
Name | Type | Notes/Example |
---|---|---|
meta[name] | STRING | Name of the resource |
meta[type] | STRING | Type of resource (entry, section, field, etc.) |
Name | Type | Notes/Example |
---|---|---|
meta[parent_id] | INTEGER | ID of the parent resource |
meta[category_id] | INTEGER | ID of the category |
Required Parameters
(meta[type] = entry)
One of the following:
Name | Type | Notes/Example |
---|---|---|
meta[section_id] | INTEGER | ID of the section that the entry will be assigned to |
meta[section] | STRING | Slug of the section that the entry will be assigned to |
Optional Parameters
(meta[type] = entry)
Name | Type | Notes/Example |
---|---|---|
fields[] | ARRAY | Entry field values (for fields that have already been assigned to the section) can be populated when the entry is created. The format is field[field-slug][field-instance]. If the field instance is left blank, it will simply be the next value in the instance array. For example: fields[network-fqdn][]=example.com&fields[network-fqdn][]=test.com would be written in JSON as var fields = { "network-fqdn": [ "example.com", "test.com" ] } Please note that the Field Slug might differ from the Field Name! To find the correct slug to use in adding resources with field values go the Section of the Resource you are adding, click 'Edit', then click the name of the Fields you will be populating. An Edit Field box will pop up which displays the Field's slug. A field can be added to a section multiple times. The field instance is used to keep track of which field occurrence we are referring. In this example, the network-fqdn field had been added twice to the section so we were able to store two values for it. |
meta[custom_id] | STRING | A custom ID for the entry. In the past this has been called the Resource Holder ID or Customer ID. Most recently it was implemented as a text field with the slug "6c-resourceholder-id." Now it is a fundamental part the entry type resources. |
Required Parameters
(meta[type] = field)
Name | Type | Notes/Example |
---|---|---|
meta[field_type] | STRING | Type of field
|
Optional Parameters
(meta[type] = field
Optional Parameters
(meta[type] = entry)
Name | Type | Notes/Example |
---|---|---|
fields[] | ARRAY | Entry field values (for fields that have already been assigned to the section) can be populated when the entry is created. The format is field[field-slug][field-instance]. If the field instance is left blank, it will simply be the next value in the instance array. For example: fields[network-fqdn][]=example.com&fields[network-fqdn][]=test.com would be written in JSON as var fields = { "network-fqdn": [ "example.com", "test.com" ] } Please note that the Field Slug might differ from the Field Name! To find the correct slug to use in adding resources with field values go the Section of the Resource you are adding, click 'Edit', then click the name of the Fields you will be populating. An Edit Field box will pop up which displays the Field's slug. A field can be added to a section multiple times. The field instance is used to keep track of which field occurrence we are referring. In this example, the network-fqdn field had been added twice to the section so we were able to store two values for it. |
meta[custom_id] | STRING | A custom ID for the entry. In the past this has been called the Resource Holder ID or Customer ID. Most recently it was implemented as a text field with the slug "6c-resourceholder-id." Now it is a fundamental part the entry type resources. |
Required Parameters
(meta[type] = field)
Name | Type | Notes/Example |
---|---|---|
meta[field_type] | STRING | Type of field
|
Optional Parameters
(meta[type] = field)
Name | Type | Notes/Example |
---|---|---|
meta[help_block] | STRING | Fields can have a line of text under them with instructions |
meta[options] | ARRAY | Fields of type radios, checkboxes, or choicebox can have multiple options. This could be multiple radio buttons or a choicebox (dropdown) with several options. For example: meta[type]=field&meta[name]=Colors&meta[field_type]=choicebox&meta[options][]=Blue&meta[options][]=Green Will create a choicebox with dropdown options of Blue and Green. |
Required Parameters
(meta[type] = gadgets)
Name | Type | Notes/Example |
---|---|---|
meta[help_block] | INTEGER | x: The nth gadget being described in the call ('0' for the first gadget, '1' for the second, and so on). uuid: User-generated ID of the gadget to be created. |
gadgets[x][code] | STRING | x: The nth gadget being described in the call ('0' for the first gadget, '1' for the second, and so on). code: Slug of the gadget code to be created. List of valid Gadget codes:
|
Example - Adding the IPAM Gadget to a Section:
api.php?target=resource&action=add&meta[type]=section&meta[name]=TestSection_1&meta[parent_id]=1&gadgets[0][uuid]=uuid-586dbd260d6ef&gadgets[0][code]=_ipam
update | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
URL | /api/v1/api.php?target=resource&action=update | |||||||||
Description | Update a resource. | |||||||||
Returns | Examples: ERROR: {"success":0,"message":"No resource found with ID: 1079"} | |||||||||
Required Parameters |
| |||||||||
Optional Parameters (meta[type] = entry) |
| |||||||||
Optional Parameters (meta[type] = section) |
|
| ||||||||||
Required Parameters (meta[type] = gadgets) |
Example - Adding the IPAM Gadget to a Section: api.php?target=resource&action=add&meta[type]=section&meta[name]=TestSection_1&meta[parent_id]=1&gadgets[0][uuid]=uuid-586dbd260d6ef&gadgets[0][code]=_ipam |
update | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
URL | /api/v1/api.php?target=resource&action=update | |||||||||
Description | Update a resource. | |||||||||
Returns | Examples: ERROR: {"success":0,"message":"No resource found with ID: 1079"} | |||||||||
Required Parameters |
| |||||||||
Optional Parameters (meta[type] = entry) |
| |||||||||
Optional Parameters (meta[type] = section) |
|
delete | |||||||||
---|---|---|---|---|---|---|---|---|---|
URL | / | ||||||||
delete | |||||||||
URL | /api/v1/api.php?target=resource&action=delete | ||||||||
Description | Delete a resource. | ||||||||
Returns | Examples: SUCCESSFUL: {"success":1,"message":"Resource deleted."} ERROR: {"success":0,"message":"No resource found with ID: 57"} | ||||||||
Required Parameters |
| ||||||||
Optional Parameters |
A recursive delete will delete all resources, which are permitted to be deleted, from the bottom up. Imagine the following hierarchy:
If a recursive delete is performed on A, but C21 is not deletable, the following resources would still be deleted: (B1, C11, C12, C22). B2 would not be deleted because it depends on C21 and A would not be deleted because it depends on B2.
, the following resources would still be deleted: (B1, C11, C12, C22). B2 would not be deleted because it depends on C21 and A would not be deleted because it depends on B2. | ||||||||
Example URL | /api/v1/api.php?target=resource&action=delete&id=57 |
get resource link | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description | Get available resource links. If no resource links exist for the given resource, an empty object is returned. | |||||||||||||||||||||||||||||||||||||||||||||||||
URL | /api/v1/api.php?target=resource&action=getLink | |||||||||||||||||||||||||||||||||||||||||||||||||
Returns | Examples:
Return Detail:
Meta Attributes:
Optional Attributes:
| Example URL | /api/v1/api
| =delete&id=57
|
get resourcelinksearch | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description | Get available resource links. If no resource links exist for the given resource, an empty object is returnedSearch the resource system for the provided term. Performs a "LIKE" search to return similar results. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
URL | /api/v1/api.php?target=resource&action=get&search=getLink | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Returns | Examples:
Return Detail:
Meta Attributes:
Required Optional Attributes:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Example URL | /api/v1/api.php?target=resource&action= | getLinkget& | relation=dhcpPoolLink&resultsPerPage=100&page=2search=6connect |