JSON Data Format

JSON is a human-readable data format used by applications for storing, transferring, and reading data. It is easy to parse and can be used with most modern programming languages, including Python.

Example 1-1 shows partial IOS output from the show interface GigabitEthernet0/0/0 command on a router.

Example 1-1 IOS Router Output

GigabitEthernet0/0/0 is up, line protocol is up (connected)
  Description: Wide Area Network
  Internet address is 172.16.0.2/24

Example 1-2 shows how this information can be represented in JSON format.

Example 1-2 JSON Output

{
    "ietf-interfaces:interface": {
         "name": "GigabitEthernet0/0/0",
         "description": "Wide Area Network",
         "enabled": true,
         "ietf-ip:ipv4": {
             "address": [
                 {
                     "ip": "172.16.0.2",
                     "netmask": "255.255.255.0"
                 }
             ]
          }
    }
}

JSON Syntax Rules

JSON data is a collection of key:value pairs that follow these rules:

• Key:value pair: One key:value pair

• Key: Text inside double quotes and before the colon that is used as the name that references a value

• Value: The item after the colon that represents the value of the key, which can be

  • Text: Listed in double quotes

  • Numeric: Listed without quotes

  • Array: A list of values enclosed in square brackets [ ]

  • Object: One or more key:value pairs enclosed in braces { }

• Multiple Pairs: When listing multiple key:value pairs, separate the pairs with a comma at the end of each pair (except the last one)

A list of IPv4 addresses might look as shown in Example 1-3. The key here is addresses. The value is an array. Inside the array, each item is a separate object, and those objects are separated by braces { }. The objects are two key:value pairs: an IPv4 address (ip) and a subnet mask (netmask) separated by a comma. The objects in the array are also separated by commas, with a comma following the closing brace for each object. After all the items in the array are defined, the array is closed with the right bracket.

Example 1-3 JSON List of IPv4 Addresses

{
  "addresses": [
    {
      "ip": "172.16.0.2",
      "netmask": "255.255.255.0"
    },
    {
      "ip": "172.16.0.3",
      "netmask": "255.255.255.0"
    },
    {
      "ip": "172.16.0.4",
      "netmask": "255.255.255.0"
    }
  ]
}

RESTful Implementation

A RESTful web service is a collection of resources with four defined aspects:

• The data format supported by the web service, which is often JSON, XML, or YAML

• The set of operations supported by the web service using HTTP methods

• The API, which must be hypertext driven

• The base uniform resource identifier (URI) for the web service, such as http://example.com/resources

RESTful APIs use common HTTP methods, including POST, GET, PUT, PATCH, and DELETE. As shown in Table 1-2, these methods correspond to RESTful operations: create, read, update, and delete (or CRUD).

RESTful API Requests

A RESTful API is requested by using a URI, which is a string of characters that identifies a specific network resource. As shown in the Figure 1-1, a URI has two specializations:

• Uniform resource name (URN): Identifies only the namespace of the resource without reference to the protocol.

• Uniform resource locator (URL): Defines the network location of a specific resource on the network.

These are the parts of a URI, as shown in Figure 1-1:

• Protocol/scheme: HTTPS or another protocol, such as FTP, SFTP, mailto, or NNTP

• Hostname: In this case, www.example.com

• Path and file name: In this case, /author/book.html

• Fragment: In this case, #page155

A RESTful API request elicits a response from the API server. For example, the URI in Figure 1-2 is a properly formed GET request to the MapQuest API server for directions from San Jose to Monterey in JSON format.

These are the different parts of the API request:

• API server: The URL for the server that answers REST requests.

• Resources: Specifies the API that is being requested.

• Query: Specifies the data format and information the client is requesting from the API service. Queries can include

  • Format: This is usually JSON but can be YAML or XML.

  • Key: The key is for authorization, if required.

  • Parameters: Parameters are used to send information pertaining to the request.

The beginning of the JSON payload delivered by the request in Figure 1-2 would look as shown in Example 1-4.

Example 1-4 JSON Payload Received from an API Request

{
  "route": {
    "hasTollRoad": false,
    "hasBridge": true,
    "boundingBox": {
      "lr": {
        "lng": -121.667061,
        "lat": 36.596809
      },
      "ul": {
        "lng": -121.897125,
        "lat": 37.335358
      }
    },
    "distance": 71.712,
    "hasTimedRestriction": false,
    "hasTunnel": false,
    "hasHighway": true,
    "computedWaypoints": [],
    "routeError": {
      "errorCode": -400,
      "message": ""
    },
(output omitted)

Ansible

Ansible uses an agentless architecture to manage network devices. Agentless means that the network device does not need code. Ansible uses SSH or NETCONF to make changes and extract information. Ansible uses a push model, as shown in Figure 1-3.

Ansible uses several text files, as shown in Figure 1-3:

• Playbooks: Files with actions and logic about what Ansible should do

• Inventory: Device hostnames along with information about each device, such as device roles, so Ansible can perform functions for subsets of the inventory

• Templates: A device configuration with variables

• Variables: A list of YAML variables that Ansible will substitute into templates

In Figure 1-3, the engineer builds all the necessary files (1). Then the engineer tells the Ansible control server to run a playbook (2), which then gets pushed to the device (3) or devices.

Puppet

Puppet typically uses an agent-based architecture for network device support. Some network devices enable Puppet support through an on-device agent. However, not every Cisco OS supports Puppet agents, and Puppet solves that problem using a proxy agent running on some external host (called agentless operation). The external agent then uses SSH to communicate with the network device, as shown in Figure 1-4.

Puppet uses a pull model to get a configuration to appear in the device, as shown in Figure 1-5.

Puppet uses several important text files with different components (refer to Figure 1-5):

• Manifest: A human-readable text file that defines the desired configuration state of a device

• Resource, class, and module: Components of the manifest, with the largest component (module) being comprised of smaller classes, which are in turn comprised of resources

• Template: A file used to create a manifest, with variable names that will be substituted

In Figure 1-5, the engineer builds all the necessary files (1) and configures the device agent or external agent (2). The agent or its proxy then pulls the configuration details (3) and updates the configuration (4), when needed.

Chef

Chef, like Puppet, uses an agent-based architecture. Chef uses several important text files:

• Resource: A configuration object whose state is managed by Chef (for instance, a set of configuration commands for a network device)

• Recipe: The Chef logic applied to resources to determine when, how, and whether to act against the resources

• Cookbook: A set of recipes about the same kinds of work, grouped together for easier management and sharing

• Runlist: An ordered list of recipes that should be run against a given device

Chef requires on-device Chef client code, and many Cisco devices do not support Chef clients, so you will likely see more use of Ansible and Puppet for Cisco device configuration management.

Table 1-3 summarizes some of the most important features of Ansible, Puppet, and Chef.

* Puppet can use an in-device agent or an external proxy agent for network devices.