1. REST API for Enterprise Communications Broker, Release 4.1.0
  2. Tasks
  3. configuration

Get a template instance for a configuration element or sub-element type

get

/rest/{version}/configuration/elementTypes/template

Retrieves a template instance of the specified configuration element or sub-element type. The template instance is a data structure containing all of the supported attributes, mandatory sub-elements, and any specified optional sub-elements for the requested element or sub-element, with default values for each attribute. Clients can request a template as a starting point for creating the data structure needed for a /configuration/configElements POST request body.

There are three ways to request a template:
  1. Top-level element and mandatory sub-elements only: if the query string only includes the elementType parameter, and the elementType value specifies a top-level configuration element, then the returned template includes all of that top-level element type's attributes plus any mandatory sub-elements - but no optional sub-elements.
  2. Optional sub-element only: if the query string only includes the elementType parameter, and the elementType value is a path to a sub-element (for example, sip-manipulation/header-rules - a forward slash-delimited list of the top-level element type and sub-element type(s)), then the returned template includes only the requested sub-element, plus any of its own sub-elements which are mandatory.
  3. Full template structure: if the query string includes the elementType parameter, whose value is a top-level element type, plus one or more instances of the subElement parameter, then the returned template includes all of the top-level element type's attributes, any mandatory sub-elements, and each optional sub-element named in a subElement parameter.

Request

Path Parameters
  • REST API version string.
    Available values: v1.1
Query Parameters
  • Specifies the configuration element type for which a template instance is requested. When requesting templates for top-level configuration element types (with or without optional sub-elements), the value for this query parameter is just the top-level configuration element type identifier (e.g., "phy-interface"). For optional sub-elements, the value is the hierarchical path to the desired sub-element, beginning with the top-level element itself (e.g., "network-interface/bfd-config/bfd-session").
  • When requesting the full template structure for a top-level element type that has optional sub-elements, there should be one subElement parameter for each optional sub-element the client wants included in the returned template. The value for each subElement parameter is the hierarchical path to the desired sub-element, _not_ including the top-level element itself, which is named in the elementType parameter (e.g., "bfd-config/bfd-session", under network-interface). The subElement parameter is included only when requesting a template for a top-level element plus one or more of its optional sub-elements.
Header Parameters
  • 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 template instance for the requested configuration element type is returned in the data section of the response.

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.
Back to Top

Examples

Example of Accessing the API with cURL

The following example shows how to get a template instance for a configuration element or sub-element type 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://${ECBIP}/rest/v1.1/configuration/elementTypes/template?elementType=access-control"

Example of Accessing the API with Python

The following example shows how to get a template instance for a configuration element or sub-element type 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://" + ecbip + "/rest/v1.1/configuration/elementTypes/template?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/>
      </attribute>
      <attribute>
        <name>description</name>
        <value/>
      </attribute>
      <attribute>
        <name>source-address</name>
        <value>0.0.0.0</value>
      </attribute>
      ...
      <attribute>
        <name>untrust-cac-failure-threshold</name>
        <value>0</value>
      </attribute>
    </configElement>
  </data>
  <messages/>
  <links/>
</response>
Back to Top