When we decided to implement an API in the Silverback by Matrix42 product, we wanted a standards-based, RESTful API. We wanted a way for any developer to connect and manage devices without needing to use the traditional administrative console. A developer might write their own web interface, create a mobile application or even directly integrate a network appliance. The point is that it doesn’t matter what the developer is doing, its a standardized way of API access.
During development of the API there were no third parties (yet!). This meant is that we needed a way to use the API as a developer to make sure the results were accurate. Of course, internally this testing is all covered and documented, but how would an external developer writing their app get a chance to tinker with the API? How could they test without an application to access the API?
I’ll start by saying that Postman isn’t the only API tool available. There are plenty that might suit different needs, but I found the features of Postman very valuable. Whether working a team or solo, these key features are what I’ll be covering in this short series of posts!
Lets start with getting the app itself from the Postman website. There are a few options they provide, like a native app for Mac OSX, Windows and Linux, but also a Google Chrome plugin. Functionally they are all similar so choose what suits you best!
When you first launch Postman, naturally there will be no configuration. What we will do next is perform some basic tests to make sure the API is working and accessible.
Generally, access to an API will require some form of authentication. This is obviously to prevent unauthorized access to data in the system. In the following example we will be connecting to a Silverback server via the API.
In the case of Silverback, we first create an API Access Token against an administrator user in the Silverback console. You can edit any user with the Administrator role in the admin console, and create a token at the bottom of the page. Note that there are many different ways to authenticate against an API, this example will show only one of them.
In the image above, we can see my access token. There is also some extra information, a description which just helps me remember what the token was for. The most important thing to note here is the Scopes field. In the example above we can see that my token has “Global Read” and “Global Write”. These can be considered to be permissions. For example if you were developing an application that simply fetched information to display, there would be no need to have the “Write” permission for this. Of course, technically there’s no reason this wouldn’t work just as well, but its best practice to only give the permissions you need.
Now that I have my access token, we can put this in to Postman and start doing some basic queries.
A Basic Query
Now that we have acquired the access token, its time to do a basic query to make sure we can get information back! Let’s take a look at a basic example:
In the above example, I’ve highlighted some key areas which we will explain briefly.
- This is the HTTP “Verb”. A “GET”, is generally what your browser does when you try to access a website. Another common verb is “POST” when your browser is submitting a form for example. For this example, make sure GET is selected.
- The API URL. This is the actual location of the API. In the case of Silverback above we are accessing the “devices” API endpoint.
- The Authorization header. With Postman you can configure any headers you would like. For our example we are going to make a header with a key of “Authorization”, and the value of “Bearer <Insert Token Here>”. This is what Postman will send to the server to authenticate.
- The response from the API. When all of the items mentioned above fit together, and you click “Send”, the server should respond with data.
The response we get back from the server in this example is a list of all devices in the system. While this example is very basic, it is fundamentally the same as any query we will do in the future with this API. We will always provide the HTTP Verb, the API endpoint and an authorization header. We will then interact with the results. Simple right?
Over the following weeks we will dive deeper into this. Specifically how we can automate Postman to do these queries for you, and how we can validate and test the data that comes back.
At this point you know how to access Silverback server and query information. I’d recommend checking out the help files if you have access to a Silverback server. You can access this from the server by navigating to: https://silverback.company.com/api/help (of course, replace silverback.company.com with your own server address). The help files describe in detail exactly what queries you can run against the system.
If you do start playing around, I’d recommend making your access token “GlobalRead” only. This will ensure that if you make a mistake you don’t end up wiping any of your devices 😉
Stay tuned for Part 2!