6.5 Interpret REST API response codes and results in payload using Cisco Catalyst Center and RESTCONF

What this objective tests

This is an interpret objective. The exam shows you a status code and a payload. You must say what happened and what to check next.

Every REST response has two parts. Read the status code first. Read the payload second. Together they tell you the result.

Response code families

Common codes you must know:

Note: 401 means authentication failed. 403 means authentication worked but permission failed. 404 means the resource does not exist. These three are the most confused codes on the exam.

Example: a RESTCONF GET request and payload

The request:

curl -u admin:Cisco123 \
  -H "Accept: application/yang-data+json" \
  https://10.10.10.11/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

The response is 200 OK with this payload:

{
  "ietf-interfaces:interface": [
    {
      "name": "GigabitEthernet1",
      "description": "WAN uplink",
      "type": "iana-if-type:ethernetCsmacd",
      "enabled": true,
      "ietf-ip:ipv4": {
        "address": [
          {
            "ip": "10.10.10.11",
            "netmask": "255.255.255.0"
          }
        ]
      }
    }
  ]
}

Read the payload field by field:

• ietf-interfaces:interface: the list from the ietf-interfaces model. The prefix names the module.
• name: the list key. It matches the key in the request URL.
• description: a configured string.
• type: the interface type from the iana-if-type model. ethernetCsmacd means Ethernet.
• enabled: the configured admin state. true means no shutdown.
• ietf-ip:ipv4: a container from a second model, ietf-ip. Models nest inside each other.
• address: a list of IPv4 addresses. An interface can hold more than one.
• ip and netmask: the address and mask as strings.

Pagination

Large responses can be split into pages. SD-WAN Manager and Catalyst Center limit result counts. The client requests more data with query parameters such as offset and limit. A script that reads only page one misses devices. Check for pagination when a list looks too short.

Lab: read a payload

This is a paper lab. A script sends GET /dna/intent/api/v1/network-device to Catalyst Center. The response is 200 OK with this payload:

{
  "response": [
    {
      "hostname": "HQ-SW1",
      "managementIpAddress": "10.10.10.12",
      "platformId": "C9300-48P",
      "reachabilityStatus": "Reachable",
      "softwareVersion": "17.9.4"
    },
    {
      "hostname": "HQ-R1",
      "managementIpAddress": "10.10.10.11",
      "platformId": "C8300-1N1S-4T2X",
      "reachabilityStatus": "Unreachable",
      "softwareVersion": "17.9.4"
    }
  ],
  "version": "1.0"
}

Answer these questions:

1. Did the API call succeed? (Answer: yes. The status is 200.)
2. How many devices are in the response? (Answer: two.)
3. What is the management address of HQ-R1? (Answer: 10.10.10.11.)
4. Which key holds the device list? (Answer: response.)
5. Are all devices reachable? (Answer: no. HQ-R1 shows Unreachable.)
6. The script does payload["devices"]. What happens? (Answer: it fails. The key is response, not devices.)
7. The same request returns 401 after the token expires. What do you do? (Answer: request a new token from /dna/system/api/v1/auth/token, then retry.)
8. A POST to the same controller returns 202 with a task ID. Is the change done? (Answer: no. Poll the task endpoint until it reports completion.)

Exam traps

• 204 is success with no body. Do not call .json() on it.
• 202 means accepted, not completed. Poll the task or job endpoint.
• A 200 with an empty list is a working API with no matching data. Check your filter.
• A 5xx points at the controller or server. It does not prove the network device is down.
• RESTCONF wants application/yang-data+json. Plain application/json can produce 415.

Pass check

You are ready when you can do these things:

• Map any common status code to its likely cause in one sentence.
• Explain the difference between 401, 403, and 404.
• Walk a nested RESTCONF payload and name the model prefix, list, key, and leaves.
• Explain why 202 and 204 are both success but need different handling.
• State what pagination does to a device list and how a client gets the next page.

Sources used

• Cisco ENCOR 350-401 v1.2 exam topics: https://learningcontent.cisco.com/documents/marketing/exam-topics/350-401-ENCORE-v1.2.pdf
• RFC 8040, RESTCONF Protocol: https://datatracker.ietf.org/doc/html/rfc8040
• Cisco Catalyst Center API documentation: https://developer.cisco.com/docs/catalyst-center/