Introduction to Postman

Postman is a free tool for development, testing, and documentation of API's.

Overview:

1. Install Postman

2. Create a new Environment, called Elentra, with two variables, url and token

3. Create a request to GET the default API route

4. Create a request to POST to the auth/login route

5. Create a request to GET the Widget route

6. Create a request to POST the logout route

Install Postman

Get the client package from https://getpostman/apps and install it

Create an Elentra environment

The add page for a new environment will look like:

Here the url is set to the default API route, which is the starting point for all other API routes. Leave the token blank, we will get Postman to populate it after logging in. The auth_username and auth_password are the credentials stored in elentra-1x-me/www-root/core/config/config.inc.php.

Create a request for the Default API route

In the main content area of Postman, there will be an empty request tab. Make sure the method is set to GET and enter {{url}} in the text box beside it. Then select the Send button. This should return the default API route, as we have seen before

You can save this route using the Save button, and it will appear in the left side so you can use it later.

Create a request for the auth/login route

Now lets create a request so that we can login to Elentra ME through Postman. Click the '+' button in the main panel of Postman to create a new request. Change the method to POST and enter {{url}}/auth/login in the textbox.

Next select the 'Body' tab below the URL, and make sure x-www-form-urlencoded is selected. Then enter the 6 form variables with their values. An example of a completed form might be:

The username and password should be the credentials for your Elentra ME installation, for the user account you want to test with.

auth_username and auth_password are the values from Elentra ME's config.inc.php file. In the case above, these are references to variables added to the Elentra environment created above. If you will have several environments with different database credentials, having these as variables can be helpful. But you can instead just copy the values in from Elentra.

Set auth_method to local and auth_app_id to 1, which should work with most default Elentra installations.

The last step is to set up the Tests tab, so that after the request is executed, Postman will capture the JWT token and save it for other requests. Open the Tests tab and enter

var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("token", jsonData.token);

Now execute the request by selecting Send. If your login is successful, you will get back some data including the token

You will also see that the token variable is set in the Elentra environment, if you click the eye button on the upper right

Create a request for the Widget route

Now that we are logged in, create a new request, set the method to GET and enter the URL as {{url}}/widget.

In the Authorization tab, select the type as Bearer Token. On the right ensure that the field contains {{token}}. This will inject our token from login along with the Widget request.

Before sending, select the Tests tab again, and enter this content, which will look for any refresh token returned by the API.

var newAuth = postman.getResponseHeader("Authorization");
if (newAuth) {
    var auth = newAuth.split(" ")
    postman.setEnvironmentVariable("token", auth[1]);
}

The reason for this test is that any call to the API with an existing token may return a refresh token if the original token is expired. Tokens generated by the API are valid for a maximum of 60 minutes. If you make an API call with the token after this interval, the request will be successful, but you will get a new token back that will be valid for the next 60 minutes and the original token will be blacklisted.

With this test in place, if the token is refreshed the Elentra environment variable will be refreshed with the new token.

Finally, select Send on the Widget request, to get a response like:

Create a request for the logout route

To round out this initial setup of Postman, lets create a request to the logout route

As before, create a new request. Set the method to POST and enter the URL as {{url}}/auth/logout. Set the Authorization tab type to Bearer Token, with the value {{token}}. You should get a result something like:

After logging out, try to run the widget endpoint again. It should now fail, because you are now logged out.