Mist API Sample Class

This is the portal for our API Docs.

Oh, I haven’t logged into it. That’s why. Yes, so you do need an account in order to access it, and this shows that.

So the first thing, actually, you need to do is to log into your Mist account from the Mist portal. So this is good because no one has the access for it other than those users who have account.

So I sign in to my account.

This is a personal account. I’m using this for the demo today.

All right, now I can log into the documentation page. So remember, you have to log in.

OK, so this is the API documentation. It’s clear.

It’s very organized. It’s separated into different sections.

For example, if you are interested in the assets, you can just click on it. And then it tells you the definition of the API.

Again, you can look at here, it looks like a URL right over here. And this is the JSON format we just talked about.

So these are the definition of the API and what’s the schema out of this particular code and what the response will look like. And this is the get, which earlier I mentioned, one of the actions you can do.

So there are a ton of APIs that Mist provide in all different areas.

So for every feature you can find on the UI, you are find in the API. Many times, there are APIs where we haven’t been able to bring it to a UI yet.

OK.

So this is a URL. There’s a lot of information. I will not go into details today.

So let me go back to the slides.

Present.

So portal, very important on the API doc. Next slide.

Which language and what are the tools? Language, Python, why is that? Because it’s one of the most popular language, that’s number one. Number two, because we use it, Mist QA, my team use it. So ensure you use it because you’ll get a better support.

If you use another language, that’s totally fine. API itself is language neutral. If you use Python, because we understand better, you will get better support– just the nature of it.

What tools?

So again, API is like a bunch of the HTTP, the URL codes.

You go to a certain URL. So you need to find some library to make these codes. Now, there is a more official solution, which is using Python request library.

If you use this, this is very portable.

You can execute it anywhere. You don’t have to modify anything.

There is, however, another solution, which I have been using for a long time. It’s a tiny program called CURL, where you can download it from here. I think that one stands for Command-Line URL, if I’m not mistaken.

So CURL is very easy to use and implemented on– yeah, command-line thing, yes, command-line URL.

So this thing is supported on all different platforms. You can download it Unix, Windows, Mac.

Actually, I think Mac and Linux probably have that by default. Or you can just install it. It’s straightforward.

So the CURL, the reason I use it is because it’s very simple to use, as you can see later in the examples. And it’s very lightweight, and I like it. So I have been using it for all my implementations.

OK, now let’s talk about token. So token is something you need to provide in order to access APIs. So token is like a representative for yourself or of your identity. Now, there’s one section in the documentation that details a lot of things about API token.

But for most of you, hey, if you just want to get this working, you probably don’t want to go into all the detail. All you want to know is, how can I generate a token?

So let me show you here how can you generate a token, the easiest way to do it.

Step one– let me exit– OK.

All right. So step one, you log into the portal– again, you log into our web portal.

Number two, you copy this URL right over here and then just paste it into the browser.

You hit Enter.

Now, this actually brings you to this page, Django REST framework, which you can totally just use this to create token.

So in the first view right over, here this lists all the current tokens. You can generate as many tokens as you like. However, that can be a security issue, so you probably don’t want to do that.

So the first page, if you don’t have any token, this would be an empty thing.

Because for this, they might just create a token, so you see one token over here. Let’s say you want to create another token. What do you do? You scroll down. You see this pattern right over here? Post. Click on that button, Post.

Now, this comes back with a new– this actually create one token right over here.

So this would be a new token.

Now, the token value is this one represented by the key right over here.

And the ID is also important because later, if you want to delete this token, you can based on the ID right over here. So once you click on the Post, our back-end will bring you to this page.

Now, the important thing is you want to save this information, especially the token. Token will only be shown once and right over here. Later, if you come back to the page, you want to find what’s the value of the token, it will not be there. So you have to copy and paste and save it somewhere. Bring a notepad or just do something about it to save this.

Now, this value, the ones that come with– next to key, that’s your token value.

So if we go back to the send link, now you see there are two tokens, right?

This one, if you remember the ID, that’s the one that we just created. And the key, you see it’s been shortened, and you won’t be able to find the true value.

So, again, very important, once you generate token, you have to save this value somewhere. Wherever you want to save it, that’s fine. But you have to save it because it only show once. Later, when you come HERE you won’t find it. You have to generate a new token, i you want to do this.

And again, just a reminder, for security concern, you probably don’t want to generate too many tokens, and you probably want to rotate your token– I mean, delete your token and create a new one every so often. So, again, the deletion can be done through the API– not through this framework, but through the API.

OK.

So this is token. And the steps I just went through, basically, it’s described it down here, A, B, C, D, E, F, G.

Now, before we start looking through example, there’s one more thing you should do, is to find out your org ID and site ID.

Because that’s how we identify– you’ll need when you write a script. And how do you find the org ID and the site ID?

One easy way I’ve been using is, go to your website. For example, this one’s the [INAUDIBLE] Office.

And the site, you pick the site you want to go to.

For example, I want to go to a trial site.

And you click on the Access Point tab.

And right on the URL, right over here, this one is org ID. You see in front of it there, it says org ID.

And the last one is the site ID.

So you’ll need these two information when you write a script. So again, the slide just describe that whole thing for you just in case you don’t remember.

All right. So I’m going to go through some examples.

So earlier, when I mentioned API can be used to create new feature, I’m not lying. Because all the features, all the scripts are listed here. Right now, if you go to the Mist UI, you won’t be able to find it.

So we work hard to catch up, but our resource is also limited. So again, so with API, you can do a lot more than limited by the UI.

Now, the first example, I will show you a Christmas light show because it’s Christmas season, right? Christmas is coming in three months. So you want to use your AP to do some light show. That’s totally cool.

The next one I’ll show you– remember I talked about the customized support in one of the reasons you want to do you want to use APIs? We’ll do a very simple one that just grab the number of 11n versus 11ac clients count. So I believe this is also not on our UI yet.

The last example is just some sort of– again, some fake example. Let’s say if you want your site to be extremely secure and you want to update your share key every week, then you can use something like that. So I’ll go into the code.

OK.

So let me see if I can make it larger. All right, I can make it large.

So when I say simple, it’s very simple. There are only 12 lines in this first Christmas light show example. 12 lines, that’s extremely simple, right? You can understand those 12 lines only.

The first one just import different libraries we’ll be using this example.

All these are very standard Python library.

I don’t think you have to install anything. This just comes by default if you have Python.

So the next one, I define a token, which is the one I just showed a couple of slides earlier on how to generate a token. The next one is the curl command I’ll be used to do this script.

The next one is site ID.

So in the script, it’s very straightforward. It says that I’m going to use the locate function in order to accomplish this light show thing.

So on the UI, when you click locate, the AP will start blinking purple light, purple LED.

So I’m going to use that.

So this is just a loop looping through four APs, 1, 2, 3, 4.

The MAC address is listed right over here.

And this is a command I’m going to use. Again, curl is like a command-line thing, so you are really simulating doing something on the browser here.

So it’s basically a POST method, and you post it to this particular access point and to this endpoint, which is our API endpoint. It’s called locate.

So if you provide the token, the proper token, that allows– our backend will authorize your action. And then, based on the API you code, you will instruct the AP to do it correspondingly. So the first one just to compose the command, the second one is to send it to my Windows laptop here. If you are using Linux, that’s exactly the same.

The next one, very straightforward, just sleep for three seconds so that you will blinking for three seconds. The next one, you will stop blinking.

And, again– I’m sorry, this is just composing the command for that. And the next one is to really send out the command.

So I am going to do this here. One second, give me a second.

All right. So let me see.

Let me see if you guys can see this. I think you should be able to see it.

One second, let me find my own camera. Very slow.

All right. So you’ll see four APs right down there.

I’m going to start the program.

Let’s see.

OK. I don’t know if you can tell that from my–

MAN: We can’t tell, David.

– You cannot?

MAN: It’s like you’re cheating us here.

– [LAUGHS] Are you serious? You cannot tell? OK, let me bring it down further. Can you tell that way?

MAN: Let’s turn off the light.

– Hold on. I think I accidentally hit stop.

MAN: OK, one more time. This better work. We paid thousands of dollars for this.

– [LAUGHS]

MAN: I see some blinking LEDs. We don’t see the purple, unfortunately, on your cheap Windows camera.

But we believe you. We trust you. We trust you. This is good.

– All right, yeah. Oh, yeah, you’ll need–

MAN: Let me ask you this, David, because I’m trying to teach my kids to be able to do API programming. What did you have to install on your laptop to actually get this to work?

– You just need to install Python, I’d say.

MAN: Python.

– That’s the only thing. For this particular purpose, that’s the only thing. Actually, I forgot to add a while loop. That’s why it only does it once. So if I do a while true, this will do it forever. Yeah, I forgot to do this.

All right. Anyway, so this is the first example. Are you all looking at it?

MAN: Yeah. No, it works now.

– All right.

Yeah, it works. Of course it works. Yes.

OK. So again, it’s very simple. So don’t be intimidated. There are only certain lines right over here.

You say this is what I want to do. You just find the right API, find the right action– in this case, POST– and call the freaking command. And then, fin, it works. That’s it, straightforward.

Now, the next example here is that we want to– it’s a little bit more, is to– give me one second to handle this camera thing.

WOMAN: I have a question, actually. It’s Python 2.7 or Python 3?

– I used 2.7,

yeah.

But 3 works fine. But 2.7 is extremely stable, so a lot of people, I think they just stuck on 2.7. And I’m one of those, so 2.7, that’s the one I’m using.

OK. So the next one is to get the number of 11n and 11ac clients.

So very familiar lines you see right over here, import the library. I do import one extra library. It’s called JSON. This is pretty cool library too. It actually make your life a lot simpler if you are dealing with our API because you can just process everything.

So token, again, similar thing, get. Now, this time, this is just reaction.

Well, it’s trying to get the number of the 11n user versus 11ac users.

So this is a get command.

This is a get URL that I’m going to code right over here.

Authorization, pass on the token for the authorization, and then the true URL will be this one. Well, actually, this is the first part, and this part is the second part.

MAN: David, if I can ask you, on the pipe, on our API list, can you show where you found that exact API?

– Yeah, absolutely.

So that’s a good question.

So they asked where we can find these particular APIs.

So go to our portal.

For example, the ones I showed before, the lightning thing, that will be under Device right over here. Device, that’s how we call our AP, because it’s a device.

And if you are not familiar with it, you probably have to go all the way through. But because I know, so I can just type locate and search it.

It’s right over here. So this is a POST action, it tells you.

This is the API endpoint, the format of it. You have to pass the site ID. You have to pass the device ID. And then this is the locate function you are going to code. And if you want to stop locating, you call unlocate right over here.

So actually, similar thing, if you want to reboot an AP, you can just call that.

It’s exactly the same. Instead of calling the locate API endpoint, you call the restart API endpoint. All right.

So the next one is the one that I am talking right now, which to grab out the 11n versus 11ac clients.

So it’s under the Site, and you have to find client, Client Stats.

That should be fairly straightforward. You are looking for a client, so you want to know the client stats.

So you click on that link.

It will bring you to here, where it gives you, again, the API URL format.

In the middle, that’s a site ID. And you are calling the stats and clients. So look at the screen, exactly the same, stats and clients. So I’m not lying here.

You just need to, again, compose the command on the things you want to call and then really call it from using this commands subprocess, check_output. This is like you do it from your command prompt, like from here.

Oh, I’m still blinking. Let me stop that.

So this one, this line right over here, line A, will call the whatever command we just composed, which pull all the stats of the current connected clients.

And that will save the result into whatever return string will save into the results. Now, this string is actually a JSON-format string. So we need to convert that into a JSON object, or in Python, that would be looking like a list– I’m sorry, a dictionary, a dictionary. So you basically just load the entire thing.

So that becomes your clients, which is a dictionary.

And then you– oh, actually, in this part of your case, it’s actually a list of dictionaries.

Yeah. But anyway, you can just print it out and find out the exact thing. So it’s actually a list of dictionaries.

So if I just go through it, looping through for each client within this client thing, if the protocol I have never seen before, I’ll set this client protocol’s count to 1 because I have never seen before.

This is the first time I’m seeing it, so I set it to one. Else, which I have seen before, then I just add 1 to whatever that protocol is. And in the end, I’m going to print out everything right over here.

OK. So the site I’m using read-only here actually is our Mist office production site, which is this one.

All right. So we have a bunch of users over here. And you want to find out how many 11n versus 11ac’s.

You hit Enter, then it tells you. 11ac, 55 users are using 11ac.

Eight users are using 11n.

Eight clients are using 11n.

Now, with some edition, you can actually just send out the email.

Again, that’s one benefit of using Python. Whatever you want to do, you can just easily google it.

So let’s say, hey, I want to send this information, email every day around 10 o’clock.

Again, that will become extremely straightforward. You just google it, how do I send email in Python? And then just copy and paste– well, not– just passing this value into whatever email you want to send and set the timer at 10 o’clock, a crontab.

That’s in the Linux. Or in Windows, you can use Scheduler to do it.

Then every day at 10 o’clock, you’ll get a report on the number of different clients in different protocol, 11ac versus 11n.

Wow. So that is something we don’t provide right now.

Even though we do have the information, but we don’t have this kind of aggregated information right over there for you. So they are creating something new here. This is just extend beyond our API.

OK.

So this is a second example.

The third example I’m going to go through is to update the PSK.

So the first example, which is a light show, this is using POST.

The second example, which gets the information, how many 11n versus how many 11ac clients, this is GET. The third one I’m going to do is a PUT, which updates the PSK key.

Now, again, this is a pseudo example. You might want to–

MAN: I’m going to interrupt you.

– Yes, no problem.

MAN: So there’s a bunch of you on the call. And for many of you, Python is new. For some of you, Python is definitely not, and you’re very much experts.

For anybody that writes a cool new script within Friday this week, I’m going to send you a $100 Amazon gift card if you post it back to David, David’s email. What’s your email, David?

david@mist.com. It can’t be easier than that.

– No, no. It’s–

MAN: davidj@mist.com?

– Yeah, or djea@mist.com.

MAN: OK, davidj@mist.com. So if any of you writes a cool new Python script on the Mist APIs for any use case you have– it could be five lines. If it works and it’s functional, I’m going to send you a $100 Amazon gift card if you send us back. Obviously, it has to be good. It can’t be printing your damn name.

That’s not eligible. So don’t try to cheat.

I can’t send $100 to everybody on. So it has to be somebody who sends the best script– look, we’re making this up, as you can see. So the best script that gets submitted by Friday that’s cool, that’s useful on the Mist API, I’m going to send you a $100 gift card.

– [LAUGHS]

MAN: Two of them, Mike?

MIKE: 200.

MAN: 200.

MIKE: The best one gets $200.

MAN: OK, the best one gets 200. For participation, we give you $25?

No, no participation. OK.

OK.

$200.

Mike just– Sujay’s going to kill us now. It’s come coming out of our paycheck. OK, so $200 for anybody submits a cool Python script using–

MIKE: The best.

MAN: –Mist API, the best one.

MIKE: The best one. There will be one winner, $200.

MAN: Yes.

– You have never done that to me.

MAN: [LAUGHS] I know. So now they’ll pay attention to this last script.

– All right. OK.

MAN: Maybe I should go on [? git. ?]

– [LAUGHS] OK, so the last one is a PUT, which allows you to update something, some information. Now, in this particular script I am showing here, we are updating the PSK key, the Wireless PSK key for whatever reason if you want to do that.

So again, very similar lines you see right here, just define different things.

It’s a GET, it’s a PUT, and what’s a Mist URL I’m using here. These are all very generic– and the site ID that I’m going to play with.

So in the first part, I define a function. It’s called new_password(). So this code’s on just some random word if you google it. I just google it about a couple of hours ago from this API. It’s free API, all right? So you can pass the words, the length of the word you want to generate. And it basically generates a random word and returns it back.

So I prepared this URL. So actually, I can just show you guys. If you just copy and paste, do that, it returns you some random stuff every time.

Renee, swagel, carve– I have no idea about these [? words ?] of this whatsoever.

So my password, my new password would be– I’m calling this thing, this API twice. And I’m just putting them together, add a space in between, and that is my new password– very straightforward. Now, in order to use this– actually, let me go back to the documentation first.

So wireless LAN is under the site, wireless LAN right over here, where you can find a lot of details about the wireless LAN definition.

So again, this is the endpoint I’m calling. Wireless LAN’s right over here.

And you can just compose the URL, which is a GET command with the [? sci, ?] and then what’s my [? sci ID, ?] and then and then the wireless LAN’s endpoint.

And then trigger that command. You will get something back, and you will you want to load that into a JSON so that it becomes like a list of dictionaries thing.

Now, the reason I do this is because I need to find wireless LAN ID.

So the wireless LAN ID is some random string that our back-end generates. And in order to modify the wireless LAN, I actually need that piece of information.

So, for example, if I just want to do a GET and show me all the wireless LAN I have here, I can actually just print wireless LAN as this ID comma– I’ll just do something, wireless LAN ID right here. All right.

Now, if I run this program– yes, update PSK.

Then it tells me all my wireless LANs, their SSID and their corresponding IDs right over here.

It’s a lot because, yeah, we test. OK.

So the ones I’m interested is actually here, the API demo, the one I just created about an hour ago for this demo purpose. And this is the ID I’m going to use.

So instead of hard code it, I make it more flexible.

So I pull the results, and then I just compare the SSID. If it’s equal to apidemo, which is the one I’m interested, I’m going to save that wireless LAN ID.

Now, if that thing is real, wireless LAN ID, I indeed find it– so I say, hey, if this thing is real, I’m going to generate a new password right over here, new password. This is new.

And then I’m preparing something for it.

It’s actually in the API documentation. Or you can actually just bring out the entire wireless LAN structure right over here. That will actually also give you a good idea of how it looks like.

So wireless LAN structure is defined right over here.

Type, the ones we are interested is PSK.

And we don’t care about the multi PSK today, so this we don’t have to pass any information about those. We don’t care about web. Don’t use web. Don’t ever use web. It’s wrong. It’s very wrong, so don’t use it.

All right. OK.

And then the passphrase is right over here.

So what you need to do is to prepare the new PSK in the exact same structure. It’s us and then PSK.

This is new. It’s the new password that we just generated. And you say the type is PSK.

Now, the POST, they’ll be tricky with CURL.

There are multiple– there are many, many ways to do it if you google it. Many people are– I think if you google it, most time, they actually use a different way to pass the data– binary, I think, something like that– to do it.

But that has not been very portable for me across different platforms. And after many trying errors, I found the uploaded file that’s actually the easiest way to do it.

So in here, I’m actually just dumping this entire thing into a file.

And this is the file name. It’s [INAUDIBLE]. It’s just a random file name I picked. So it’s dumping the entire thing into the file. And then I call my PUT command, which is defined right over here, blah, blah, blah, blah, blah. Oh. In here, it tells you the content is actually a JSON content, right over here.

Now I update that file, which contains the structure I just defined, with the new password– and plus the URL, which is right over here, the ones I define right over here, and then the site ID, the wireless LAN, and then the wireless LAN ID. I trigger that. And that will bring me the new password.

So let’s try this.

OK. Before I do it– oh, oops not this one.

So this is the wireless LAN we are looking at– not office, the trial– in the network, wireless LANs API demo, the first one.

Right now, you can see this is the passphrase, royal mamas whatsoever. I refresh it just to show you this is true. I’m not lying here.

So trigger the script.

Let me clear the screen.

You just hit Enter, and it prints out the new password. It’s with board, blah, blah, blah.

In the browser here, you refresh it, hit Reveal, then exactly something you just provisioned, all right? Now try again. Let’s try something different.

This time is pygmy idiot. [LAUGHS] All right. OK, cool. So refresh, reveal.

And right over there– just in case you couldn’t see it, right over here. So now, if you add some more things– again, if you hook up email, you can just totally send every Sunday night at 12:00 AM, you change your passphrase and then you send email to the entire company and say, hey, for this week that’s the new passphrase.

So that’s for all the examples I have prepared for today. And thank you for participating. And, yeah, looking forward for you guys’ submission before Friday. That’s pretty cool.

MAN: You’re going to pick the winner, David.

And, Mike, I know there’s a lot of people here– this bill can get out of hand– but I want to give $25 for anybody who submits. And Mike Bram, hello world is not allowed.

That is not a valid submission. So $25 for anybody that submits an–

MIKE: I love it.

MAN: –API script and $200 for the very best one. Bryce, don’t let me down. I’m watching you. So all right. Mike, you’re up.

– I’m going to cut my video feed.