Get one or more configuration element instances
/rest/{version}/configuration/configElements
- For configuration element types that are singletons, which have no key attributes, the only query parameter included in the URI is elementType.
- For element types that can have multiple instances, the query string must include "&name=value" for each key attribute, where name is a key attribute name and value is the associated value. The order of the key attributes in the query string does not matter. The key attributes for an element type are identified in the metadata (/configuration/elementTypes/metadata).
If multiple instances are requested, omit all key attribute query parameters to get all configured instances of the specified element type, or supply the offset and maxElements query parameters to limit the response data to the desired subset, for those element types that support paging.
By default, the instance data returned in a GET response is from the edited configuration. If the client wishes to retrieve the current running configuration instance data, include the optional "&running=true" in the request query parameters.
Request
-
version:
REST API version string.
Available values: v1.2
-
elementType:
Indicates the configuration element type being retrieved.
-
maxElements(optional):
The maximum number of configuration element instances that is returned in a paged response. If there are not maxInstances element instances in the requested result set, then the response contains fewer instances than maxInstances.
-
name=value(optional):
Specifies the name and value for one key attribute of the elementType. For elementTypes having multiple key attributes, each one must be represented by "&name=value" in the query string. This query parameter is omitted entirely for singleton element types, which by definition have no key attributes, and when requesting more than one instance.
-
offset(optional):
When requesting multiple instances of a configuration element type that supports paging and a subset of all configured element instances is desired, offset must be supplied and specifies, using a 1-based index, the first instance that is returned in the response.
-
running(optional):
When included with a value of true, the instance data returned in the response is from the running configuration. When omitted the instance data returned is from the edited configuration.
-
Authorization:
The value in the Authorization header must be the string "
Bearer {access token}
", where{access token}
is a valid, unexpired token received in response to a prior/rest/{version}/auth/token
request.
Response
200 Response
400 Response
401 Response
404 Response
Examples
Example of Accessing the API with cURL
The following example shows how to get one or more configuration element instances by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.
curl -X GET \
--header "Accept: application/xml" \
--header "Authorization: Bearer $TOKEN" \
"https://${SBCIP}/rest/v1.1/configuration/configElements?elementType=access-control"
Example of Accessing the API with Python
The following example shows how to get one or more configuration element instances by submitting a GET request on the REST resource using Python. This example assumes you have a valid token stored in the token
variable. For an example of authenticating with Python, see Authenticate.
import requests
headers = { "Accept":"application/xml", "Authorization":"Bearer " + token }
url = "https://" + sbcip + "/rest/v1.1/configuration/configElements?elementType=access-control"
resp = requests.get(url, headers=headers)
Example of the Response Body
The following example shows the contents of the response body in XML format.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<data>
<configElement>
<elementType>access-control</elementType>
<attribute>
<name>realm-id</name>
<value>core</value>
</attribute>
<attribute>
<name>description</name>
<value>example access-control element</value>
</attribute>
<attribute>
<name>source-address</name>
<value>10.0.0.0/24</value>
</attribute>
<attribute>
<name>destination-address</name>
<value>10.0.1.0/24</value>
</attribute>
<attribute>
<name>application-protocol</name>
<value>SIP</value>
</attribute>
<attribute>
<name>transport-protocol</name>
<value>TCP</value>
</attribute>
<attribute>
<name>access</name>
<value>permit</value>
</attribute>
. . .
<attribute>
<name>last-modified-date</name>
<value>2019-01-11 18:08:15</value>
</attribute>
</configElement>
</data>
<messages/>
<links/>
</response>