To define an API, an API is an application programming interface where your server, in this case, a CX switch, or clear paths, or the web, central service that we have, that vendor that created that service can provide different commands, not just through command line but through an API. These APIs allow us to use common web-based interactions to be able to talk to them. Traditionally, it was remote procedure calls or SOAPs, SOAP is a Simple Object Access Protocol language that was used mainly with web and XML. These days, you're almost always going to lean on REST API calls just because of their flexibility and their popularity. REST stands for Representational State Transfer and that's what it is. Think of it as a web protocol to be able to take a client like your laptop and access a server like, for example, a CX switch. You are sending these requests. The requests will take the format that makes sense to you. Either you can send them in XML or JSON or just as raw HTTP, HTML requests, but it also needs to agree with the server, or some servers may only support JSON, for example. You need to have an agreed format. XML and JSON are the two most popular, probably JSON because of its ease to program in languages like Python. The client's state would indicate that the client has logged in to the servers successfully, will have some token from the server saying, yes, I have logged you in, either the client uses a username password, or certificate, or decrypted hash, or whatever they're using to be able to validate they have rights on this machine before they make that request. Then the request itself can take the form of a method, in other words, the thing that you want to do, what action do you want to take on this switch? This particular method is a getMethod, which means I want to get information from that switch. After they've posted your authentication and you've gotten your token, you include that token whenever you make these future requests until the token expires and you renew it. With this simple requests, and this is a bit dumbed down, but it would be some Universal Resource Identifier, in this case, a URL indicating the web address of the server that you're going to, the IP address of the switch, in this case, using REST, using the servers or switches 10.04, the most up-to-date version, and you're asking for VLANs. You're trying to get a list of VLANs from this particular address. This is known as a Universal Resource Indicator or identifier in the form of a URL. Ninety-nine percent of the time it's going to be these URLs. Just the nature of the beast. With this, you would expect a response saying, hey, that request worked okay, here's your results coming in this direction, and it would include the body of your results, known as the body or the payload if you will, and the status of the message. The status would indicate the request was successful if it's a 200s and then we're in the 200s, if it's unsuccessful, it'll be in the 400s or 500s. These are standard HTML web-based error codes that if you've used any web service or anything like that, these codes have been going on back-and-forth between your browser and servers for since the web was intercepted. A 200 is a standard, any 200 code usually means things are working out great. We can see that because now we've gotten some JSON information here, such as the VLANs. It doesn't just give them as a text file, what it does is it formats them in the requested JSON format and it includes the key, the identifier, and another key, the name, and these are populated by the values. If you have one VLAN, the key might be ID, 10, and the name, VLAN 10. If you have 100 VLANs, you would see ID, name, ID name, and those would be populated by the lists of different VLAN information. Now our client machine, our user has populated this list rather than having to go login, know what the commands are on this particular switch, on this particular vendor, on this particular version of the code, and do a show commands, show VLANs or whatever, and then somehow copy it and paste it into whatever. This is easily parsed and you could push this wherever you want. REST API concepts, we have methods like GET, which retrieves data, POST, which creates a new resource. If you're going to POST or PUT something which updates a resource, this involves the user sending a payload to the actual server. Their requests should include with POST and with PUT some body in their message. Like, you want to post a list of VLANs or you want to put new names on your existing VLANs. You can do that, but you need to indicate what VLANs and what you're posting or what you're changing. With DELETE and GET, we can often get away with just sending the actual URL, and whatever resource we're getting, it sends us that resource. Whatever resource we're deleting, it deletes that resource. Some resources cannot be deleted, like if you want to get your current CPU usage, what percentage of CPU is being used, that's a GET request. You can't post it, you can't delete the CPU, you can't update the CPU, it's just a GET-only request. That would be indicated in swagger. Anytime you look at the swagger interface, it would say what methods are available and how to test them and what format they should be in, and really just give you an example that you can copy and then just edit the parts that you want to. When we are sending these requests, the header will include things like the host that we're trying to go to, where the request originated from, so the host are the IP address of the client, the format the client is expecting the information in, and in the header, we'll typically include maybe some additional user agent information where the request was sent from.
