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" |
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 | General Parameters:
At most, one of the following:
Limit Results by ID: At most, one of the following:
| ARRAY | Get any resource whose parents have any of these IDs |
INTEGER | The resource id from the standard resource table, used in conjunction with 'getFromBackup'. | |
custom_id | INTEGER | The resource custom id provided by the user for the resource. |
resource_ |
_in | ARRAY | Get |
any resource which has any of these IDs |
At most, one of the following:
Syntax: &resource__in[]=1771&resource__in[]=14238 (Each resource id you wish to search over gets its own phrase.) |
resource__not |
_in | ARRAY | Get all the resources |
which do not have any of these IDs |
Syntax: &resource__not_in |
[]=1771&resource__not_in[]=14238 (Each resource id you wish to exclude gets its own phrase.) |
At most,
one of the following:
Name |
---|
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 :
- ASC (default)
- DESC
You can further limit the results based on attributes the resources may have
Type | Notes/Example | |
---|---|---|
parent_id | INTEGER | Get the resources whose parent has this ID |
parent__in | ARRAY | Get any resource whose parents have any of these IDs. Syntax: &parent__in[]=162&parent__in[]=299 (Each parent id you wish to search over gets its own phrase.) |
parent__not_in | ARRAY | Get all resources whose parents do not have any of these IDs Syntax: &parent__not_in[]=1771&parent__not_in[]=14238 (Each parent id you wish to exclude gets its own phrase.) |
At most, one of the following:
Name | Type | Notes/Example |
---|
category_ |
id |
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:
- = (default)
- !=
- ﹥
- ﹥=
- ﹤
- ﹤=
- LIKE
- NOT LIKE
- IN
- NOT IN
- BETWEEN
- NOT BETWEEN
Note |
---|
When attr_compare is set to IN, NOT IN, BETWEEN, NOT BETWEEN, then attr_value must either be an array or a comma separated string. |
You can search on multiple attributes by including an array of attribute options:
Name | Type | Notes/Example |
---|---|---|
attributes | ARRAY | 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 |
INTEGER | Get the resources of the category that has this ID | |
category__in | ARRAY | Get any resources whose categories have any of these IDs. Syntax: &category__in[]=11002&category__in[]=11003 (Each category id you wish to search over gets its own phrase.) |
category__not_in | ARRAY | Get the resources of all the categories that do not have any of these IDs Syntax: &parent__not_in[]=11002&parent__not_in[]=11003 (Each category id you wish to exclude gets its own phrase.) |
Limit Results by Resource Link:
For resources for which exist a Resource Link, you may limit by resource link data:
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 } | ||
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 |
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]=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":{}}}} /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"} | ||||||||||||
Required Parameters |
| ||||||||||||
Optional Parameters |
| ||||||||||||
Required Parameters (meta[type] = entry) | One of the following:
| ||||||||||||
Optional Parameters (meta[type] = entry) |
| ||||||||||||
Required Parameters (meta[type] = field) |
| ||||||||||||
Optional Parameters (meta[type] = field) |
| ||||||||||||
Required Parameters (meta[type] = gadgets) | |||||||||||||
add | |||||||||||||
URL | /api/v1/api.php?target=resource&action=add | ||||||||||||
Description | Add a resource. | ||||||||||||
Returns |
Example - Adding the IPAM Gadget to a Section: | api.php?target=resource&action=add&meta[type]=section&meta[name]= | apitestTestSection_1&meta[ | typeparent_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: entry&meta[section]=firewall&fields[network-fqdn][]=www.example.com ERROR: {"success":0,"message":"Entries must be assigned to a sectionNo resource found with ID: 1079"} | ||||||||||
Required Parameters |
| ||||||||||
Optional Parameters |
| ||||||||||
| |||||||||||
Optional Required Parameters (meta[type] = entry)One of the following: |
| ||||||||||
Optional Parameters (meta[type] = entrysection) |
Required Parameters (meta[type] = field)
|
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 |
| |||||||||
Optional Parameters (meta[type] = field) |
| |||||||||
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) |
|
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. | ||||||
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:
|
get resource search | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description | Search 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= | ||||||||||||||||||
Returns | Examples: | ||||||||||||||||||
delete | |||||||||||||||||||
URL | /api/v1/api.php?target=resource&action=delete | ||||||||||||||||||
Description | Delete a resource. | ||||||||||||||||||
Returns | Examples: SUCCESSFUL: {"success":1,"message":"Resource deleted."} ERROR:
Return Detail:
| Optional Parameters
| Name
| Type | Notes/Example | ||||||||||||||
recursive | BOOL | When 1, deletes parent and child entries for the resource |
Code Block |
---|
A
B1 B2
C11 C12 C21 C22 |
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 resource name | ||
slug | STRING | The resource slug |
type | STRING | The resource type. |
parent_id | INTEGER | ID of the parent resource |
category_id | INTEGER | ID of the resource category type |
date | INTEGER | Resouce creation date |
modified | INTEGER | Resource last modified date |
attr | JSON | A JSON list of resource attributes |
Required Attributes:
Name | Type | Description |
---|---|---|
search | STRING | The search term |