Jump to

• Request
• Response
• Examples

Get one or more configuration element instances

get

/rest/{version}/configuration/configElements

Retrieves one or more instances of the specified configuration element type. If a single instance is requested:

• 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

Path Parameters

• version:
  REST API version string.
  Available values: v1.2

Query Parameters

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

Header Parameters

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

Back to Top

Response

200 Response

The instance data for the requested configuration element(s) is returned in the data section of the response. If the client is requesting all instances of a specific type (paged or not) and the system configuration includes no instances, 200 OK is returned, and the section of the response body is empty.

400 Response

The request is malformed in some way or is missing required information and therefore cannot be processed.

401 Response

Unauthorized - Request lacks valid authentication credentials.

404 Response

Unsupported versionId in URI, or requested element type not supported, or element instance specified by key attribute(s) not found

Back to Top

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 Headers

The following shows an example of the response headers.

HTTP/1.1 200
Server: nginx/1.14.1
Date: Wed, 01 Apr 2020 13:49:39 GMT
Content-Type: application/xml
Transfer-Encoding: chunked
Connection: keep-alive

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>

Back to Top