2. Trigger POEMS API Login (authorize API)

The authorization endpoint triggers POEMS API login which requires user to login with POEMS account.
Refer to Quick Reference for user login credentials.
After you are logged in, click "View Orders"

Open views/html/index.html in the sample application and look for the following lines of code:
index.html file will be the frontend(client side) code

//function to redirect to POEMS API login page

function callLoginApi() {

	var authorizeUrl = authApiUrl + "?response_type=code"
	+ "&client_id=" + clientId
	+ "&deviceId=MyDemoFP"
	+ "&state=" + state
	+ "&redirect_uri=" + redirectUrl;
	window.location = authorizeUrl;
}
                    

This code triggers the authorize API.

It calls the AUTH API URL below (with some additional parameters):


Note that this API is using HTTPS GET.
You will notice that the URL contains the following parameters:

a) Login with POEMS Account

Use this test ID and password to login to POEMS API Gateway:
User Name: 2222222 Password: 156156qw

b) Get the Authorisation Code

If you have followed the steps above correctly, the authorize api should return you an authorisation code by accessing your callback URL. You should now see something like this in your server side callback.


The dialog below shows the server side callback function.

/* GET callback. */
router.get('/callback', function (req, res, next) {

	if (!_.isUndefined(req.query.code) && !_.isEmpty(req.query.code)) {
		//recieve access code from authorize api after login
		console.log("access code: ".yellow + req.query.code.green);
		// exchange access code for access token
		callTokenAPI(req.query.code, false,
			function (data) {
			...

		} else {
			res.send("You are not authorize to see this page.");
		}
	...
                    

Notice the parameter code - It is the authorisation code that your application will used to invoke the next API (token). In the example above, the authorisation code is c516Bn. We will use this authorisation code in the next token API call.

The token API calls will follow once you have received the code in the server side.
We will look at the code for token APIs in the following sections.

3. Call the Token API (with the authorisation code)

Now that you have the authorisation code, you can invoke the token API to get the access token.
In the sample application we call this API from a server-side component. It is recommended that it should not be called from the browser or mobile native client application to prevent exposing access token to unauthorized entities.
Open routes/index.js in our sample client application and search for the following:

index.js is the backend (server side) code.

//to prepare request for access TOKEN API
function prepareRequestForAccessToken(code) {
	var cacheCtl = "no-cache";
	var contentType = "application/x-www-form-urlencoded";
	var result;
	// assemble params for Token API
	var strParams = "grant_type=authorization_code" +
		"&code=" + code +
		"&redirect_uri=" + _redirectUrl +
		"&client_id=" + _clientId +
		"&client_secret=" + _clientSecret;

	var params = querystring.parse(strParams);

	...
	
	result = {
		params: params,
		headers: headers
	}
	return result;
}

// function to request for TOKEN API
function callTokenAPI(tokenParam, isRefresh, callback) {

	var headers;
	var params;
	var requestHeadersAndParams;
	// determine token parameters for access token request or refresh token request
	if (isRefresh) {
		requestHeadersAndParams = prepareRequestForRefreshToken(tokenParam);
	} else {
		requestHeadersAndParams = prepareRequestForAccessToken(tokenParam);
	}

	headers = requestHeadersAndParams.headers;
	params = requestHeadersAndParams.params;

	var request = restClient.post(_tokenApiUrl);

	...
}
                    

The code is creating the request to call TOKEN API:



Note that this API is using HTTPS POST.
The parameters in the POST body are as follows:



The sample application will then send the constructed request to the API Gateway, and you should see the following response from the npm console logs:



Notice the response contains an "access_token" and "refresh_token", which is in the JWT (JSON Web Token) format. We use "expires_in" to determine token expiration time. If the token is expired we call token API to request for new access token. We will describe the token renewal process below
NOTE: token contains built-in additional information about login user session which is also encoded in the access_token string to be determined by Gateway. We will only need the encoded access_token in order to successfully call the POEMS API.

4. Call the Refresh Token API (access token is expired)

Now that you have the refresh token, you can invoke the token API to get the new access token.
NOTE: Our JWT access token is a stateless session token. Expires_in determine when access token will expire. To avoid session time out, we check token expire each and every call. If token expired, we call refresh token api to request for new access token. Unlike token api request, refresh token api request does not require user to authorize again.

Open routes/index.js in our sample client application and search for the following:

index.js is the backend (server side) code.

//to prepare request for refresh TOKEN API
function prepareRequestForRefreshToken(refreshToken) {
	var cacheCtl = "no-cache";
	var contentType = "application/x-www-form-urlencoded";
	var result;
	// assemble params for Token API
	var strParams = "grant_type=refresh_token" +
		"&client_id=" + _clientId +
		"&refresh_token=" + refreshToken;

	var params = querystring.parse(strParams);

	...
	
	result = {
		params: params,
		headers: headers
	}
	return result;
}

// function to request for TOKEN API
function callTokenAPI(tokenParam, isRefresh, callback) {

	var headers;
	var params;
	var requestHeadersAndParams;
	// determine token parameters for access token request or refresh token request
	if (isRefresh) {
		requestHeadersAndParams = prepareRequestForRefreshToken(tokenParam);
	} else {
		requestHeadersAndParams = prepareRequestForAccessToken(tokenParam);
	}

	headers = requestHeadersAndParams.headers;
	params = requestHeadersAndParams.params;

	var request = restClient.post(_tokenApiUrl);

	...
}  
                    

The code is creating the request to call TOKEN API:



Note that this API is using HTTPS POST.
The parameters in the POST body are as follows:



The sample application will then send the constructed request to the API Gateway, and you should see the following response from the npm console logs:

5. Call the POEMS API (with the access token)

Now that you have the access token, you can invoke the token API to get the data.
Click HERE. for more info about the POEMS API
NOTE: This API should be called from a server-side component.

You will need to provide a valid access token or your API call will be rejected.
Open routes/index.js in our sample client application and search for the following:

index.js is the backend (server side) code.

//function to call orders api
function callTodayOrdersAPI(accessToken, callback) {

	var result;
	// assemble params for orders API
	var strParams = "osVersion=1" +
		"&language=1";
	var params = querystring.parse(strParams);

	// assemble headers for orders API
	var strHeaders = "x-api-key=" + _x_api_key;
	var headers = querystring.parse(strHeaders);
	_.set(headers, "Authorization", "Bearer " + accessToken);

	...
	
	var request = restClient.get(_todayOrderApiUrl);

	...
}
                    

The code is creating the request to call the following POEMS API:



Note that this API is called using HTTPS GET.
The additional parameters are as follows:



Providing the Access Token in the Request Header
The access token should be provided in the header of your API call under "Bearer".
You should see something like this in the npm console logs:



Once this is done, you should see the orders JSON in the npm console logs that looks like this:

5. Use the JSON object to Show data

If you have followed the steps above correctly, you should have gotten the data JSON object from poems api.

SUMMARY

You've successfully used the OAuth2 process to get the data from POEMS API sandbox environment.