Resources
Warning |
---|
ProVision's APIv1 system has been replaced by APIv2, and is now considered deprecated. |
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:
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
Limit Results by ID: At most, one of the following:
At most, one of the following:
| 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:
|
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 |
add
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"}
Name | Type | Notes/Example |
---|---|---|
meta[name] | STRING | Name of the resource |
meta[type] | STRING | Type of resource (entry, section, field, ect) |
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" ] } 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. |
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) |
|
At most, one of the following:
Limit Results by Resource Link: For resources for which exist a Resource Link, you may limit by resource link data:
Limit Results by Attributes: You can further limit the results based on attributes the resources may have:
Result Ordering:
Range Selection / Paging: You can restrict the range of the resources returned.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Example URL | /api/v1/api.php?target=resource&action=get&id=7 |
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) |
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 | /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. | ||||||||
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 |
Required Attributes:
|
Name | Type | Notes/Example |
---|---|---|
recursive | BOOL | When 1, deletes parent and child entries for the resource |
A recursive delete will delete all resources, which are permitted to be deleted, from the bottom up.
Imagine the following hierarchy:
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.