- [Instructor] Before examining some very common
API Response Codes, we need to know that there
are two common data formats
that we'll see used with REST APIs.
And those are, XML and JSON.
XML stands for, Extensible Markup Language.
If we look at an example of XML,
this format might look familiar to you,
especially if you've worked with constructing Web Services,
it's very common for that usage.
This is a tag-based language, so every item must have a tag
enclosed between angle brackets.
So here the first item is called, note, in this example,
we also have different subitems,
and parameters also enclosed by their own tags.
The overall note here contains items for the to,
from, the heading, and the body as well.
Notice that each item also ends with the same name tag
proceeded inside the angle brackets by a forward slash,
which indicates the end of the item.
One of the key features of XML, is that it's easily readable
by humans and software.
The indentation you see in this example,
isn't necessary for applications to read it,
but that's simply a way that we format the data
so that we can easily interpret that ourselves.
And it's also considered a best practice when programming.
The other day the format to examine
is the JavaScript Object Notation format,
called, JSON, for short.
This is gaining popularity and may
even replace XML completely at some point.
Here, you can see that just as with XML,
this is a very readable format for humans,
and likewise, the indentation is a best practice
that helps to facilitate that.
We can see here a list of three employees
in this very simple example,
and they're arranged in name value pairs.
JSON uses name, value pairs.
Each name precedes the colon,
and is placed inside parentheses,
while the value related to the name follows the colon,
and is also placed in parentheses.
As for Cisco DNA Center, this architecture expects all
of the incoming data that comes into the device
to be formatted in JSON format.
When you have the need for maybe more advanced APIs,
or perhaps custom actions that have no existing APIs
that will accomplish what you're looking for,
then you can begin creating and streamlining your own APIs.
The tool of choice for this with Cisco DNA Center,
is called POSTMAN.
POSTMAN can be configured and authenticated
with our Cisco DNA Center Controller,
so that we can perform API calls through POSTMAN.
Common ways we might use this would be
to quickly send an API call to the DNA Center,
that would output a list of our entire network inventory,
along with information about each device.
POSTMAN uses HTTP GET operations,
in order to send those API calls to Cisco DNA center.
When those calls are made,
there are several potential HTTP status codes
that may be returned, which you should be familiar with.
Being familiar with these codes is going
to help you more quickly troubleshoot your API calls,
depending on which status is returned back.
Here I have my own version of POSTMAN launched.
And so let's take a look at that.
Now, although we won't use this directly with DNA Center
in my case, I do want to show you around the interface,
and show you the general operation of that.
If I go here and begin a new request,
then we can go in here and point
that to anywhere that we want to.
And I'll actually just point that to the public Internet.
I'm just going to say, I'm going to point it to google.com.
And you can see that this is a GET request that I have,
you can obviously do other things,
but I'm going to choose GET, and then I'm going to hit send.
And you can see that that does return
an output down at the bottom.
And this is a the XML coding in the body.
In this window, notice that it defaults to the view called,
Pretty, which is more readable by humans
but we can also look at the raw data.
And you can see right away
that's much more difficult to interpret.
We can also use the Preview Window to see this,
since it is a website resource.
And again, the Pretty view is going to be normally
what we want to see because that's much,
much more easy for us to read.
So this is the basic principle that you'll use
when you use POSTMAN with Cisco DNA Center as well.
Cisco DNA Center has extensive documentation
around their APIs, and it lists out the different paths
that you can point POSTMAN towards, in the address bar.
Notice also if I scroll back up,
that we see the status listed here.
We have a 200 Okay status.
And so that is an HTTP response code.
That's the first status code that we want to remember.
Codes in the 200 range means success in general.
And that code 200 means that a GET or POST command
was successfully used to exchange data with an API.
Let's look at a few more
of those common Status Return Codes that we might see.
So we've already seen the 200 code,
meaning that there was a successful GET or POST command,
we also might see a status code, 201, created.
And that means that a resource was created.
So if we sent out a POST request for creating a resource,
201 indicates that this was successful.
Status codes in the 400 range
indicate some sort of client side error in general.
A 400, BAD REQUEST status, means that there's a problem
with the syntax that the client is using.
And that the syntax coming into the server
was not able to be understood by that server.
Status Code 401, UNAUTHORIZED,
means that there is user authentication required.
If there were included authentication credentials
in the original request that was sent from the client,
this means that they were refused for some reason,
and most likely, the reason is that they do not
have the appropriate permission levels associated
with their user account.
Status code 403, FOBIDDEN,
means that the request was received
and understood by the server,
but that the server is refusing to fulfill the request.
The reason for the refusal will be included
in the description of the return code,
which is usually based around credential problems.
And status code 404, NOT FOUND,
means that no data matching the request
was recognized on the server
and that there's nothing to return back.
You've probably experienced this one
more than any of those mentions so far,
especially if you've ever gotten a 404 website error,
for a link or a web page that no longer exists.
And as a note, if you see codes in the 500 range,
this indicates that there are server side errors,
where the server has encountered some sort of condition
that keeps the request from being fulfilled.
This can range from network delay issues and bandwidth,
to insufficient storage and many more problems.
So that's a look at REST API Response Codes,
particularly some of the most popular ones
that you're likely to be exposed to,
if you interact with DNA Center,
through an API development platform, such as POSTMAN.