REST Response Codes and Payloads

What it is

Every REST reply has a status code and usually a body, and you read both to learn what happened.

The status code is a three digit number that tells you whether the request worked, and if not, whose fault it was. The body, called the payload, holds the data or the error details. Reading them together is how you debug an API call.

How it works

The first digit of the code tells you the class, and the payload gives the detail.

Status code classes

Codes to know

A useful habit is to read the first digit. A 4xx means to check your request, and a 5xx means that the problem is on the server.

RESTCONF results

RESTCONF uses status codes in line with the method.

If a GET returns 404, the data path is wrong, or the data is not configured. A 400 often means invalid JSON or a value that does not fit the YANG model. A 401 means a login failure.

An error reply from RESTCONF has a standard body.

{
  "ietf-restconf:errors": {
    "error": [
      {
        "error-type": "protocol",
        "error-tag": "invalid-value",
        "error-message": "The value does not match the model"
      }
    ]
  }
}

The error-tag is a short code, and error-message gives a human readable reason. Read these before you try again.

Catalyst Center results

A successful Catalyst Center call returns 200 and a JSON body. A list reply wraps the items under a response key. A call that starts background work returns 202, and the body holds a task identifier.

{
  "response": {
    "taskId": "TASKIDVALUE",
    "url": "/api/v1/task/TASKIDVALUE"
  },
  "version": "1.0"
}

The client then asks for the task until it reports that it finished, and reads the outcome from there. The first reply only says that the work started, so it does not prove that the change was made.

An error reply from Catalyst Center holds a message that explains the problem. A 401 means the token is missing or has expired, and the fix is to ask for a new token.

Reading a payload in Python

Check the status code first, and then read the body.

resp = requests.get(url, headers=headers, verify=False)

if resp.status_code == 200:
    body = resp.json()
    for dev in body["response"]:
        print(dev["hostname"], dev["reachabilityStatus"])
elif resp.status_code == 401:
    print("Login or token problem")
elif resp.status_code == 404:
    print("Check the path")
else:
    print("Unexpected status", resp.status_code)

The function resp.json() turns the body into a Python dictionary. A 204 reply has no body, so calling it would raise an error.

A method for reading results

1. Read the status code. Decide if the problem is the client, the server or none.
2. If it is a 4xx, read the error body for the reason.
3. If it is a 2xx with a body, find the key that holds the data.
4. If it is a 202, find the task and check its result.
5. Fix one thing at a time, and try again.