OPEN API Test Guide

2-2.  Download and install

Please download and set up the installation program from https://www.getpostman.com/ that fits your OS. You can install and use Postman on Windows, Mac and Linux.

Note
 As Postman is not provided by Coupang, we provide just general information of how to set up but not overall information on Postman. 

3. Set up Postman environment

 You can define the parameters (parameter used for API call) which are used frequently in Postman in the form of key/value pair in advance and use them changing when necessary.

In this guide, we recommend to set the following values in the environment to use them. 

• vendorId : vendor ID(You can check it on Wing)
• OPENAPI KEY : Openapi key issued from Coupang Wing
• SECRET KEY :  Openapi secret key issued from Coupang wing

You can change or set up the environment from the combo box on the right top. 

If you click the list of environment set, you can add, change or delete individual items. 

Here, we configure as above referring to the items provided on Wing.

Note
When vendor ID or Openapi key info is a pair, it is ok to input them yourself when calling API without making the environment but if you use it you can configure API test info in an easier way.

4. API Test

Lets investigate how to call product list paging query API using Postman.

4-1. Input URI & Method

Check the URI(Path) and Method (GET/POST/PUT/DELETE, etc) of the API from developers portal and also check whether the Path segment parameter exists in the URI. Here, you need sellerProductId. 

 

Configure API requests as in the above image based on what you checked from developers portal.

 

Set up environment
Check if the environment described in the previous chapter is correctly designated. 

Use binding parameter(:name of parameter)
You can enter sellerProdcutId value in the URI field but when you test it changing the values, configure URI with ":parameter name" format. Then you can input the values in the form of key/value format in the Params tab as in the image. 

4-2. Input Request header

When calling API, not just URI and Method but also parameter and header values have to be sent. Coupang open API requires two header values : 'Authorization' and 'X-Requested-By'.

• Authorization : To get verification when calling API, HMAC string is required and pre-script which will be described in 4-4 creates and provides it dynamically. When inputting parameter in the \{\{signature\}\}  format, the value created by pre-request script is provided in the global variable format. 
• X-Reqeusted-By : VendorId to check API requester. When inputting parameter in the \{\{vendorId\}\} format, vendorID value set in the environment is automatically provided. 

4-3. Input Request Parameter

Like the API of querying place of shipment in the example below, the parameter which has searchType=FULL at the end of '?' of URI is called 'Querystring Parameter'. The querystring parameter entered in the URI window as in the image below is also displayed in the Params tab and the value changed here is also reflected to URI window. 

Enter the Header and Query String parameter according to the API call spec that you checked from Developers portal.

4-4. Write a pre-script to create HMAC

For OpenAPI test, HMAC(Hash-based Message Authentication Code) string is needed. Postman can dynamically create HMAC via pre-request script feature which is as in the following:

var CLIENT_KEY = pm.environment.get('CLIENT_KEY');
var SECRET_KEY = pm.environment.get('SECRET_KEY');
var AUTH_TYPE = 'CEA algorithm=HmacSHA256';

function getPath(url) {
          var pathRegex = /.+?\:\/\/.+?(\/.+?)(?:#|\?|$)/;
          var result = url.match(pathRegex);
          return result && result.length > 1 ? result[1] : '';
}

function getQueryString(url) {
          var arrSplit = url.split('?');
          return arrSplit.length > 1 ? url.substring(url.indexOf('?')+1) : '';
}

function getAuthHeader(httpMethod, requestUrl, requestBody) {

          var requestPath = getPath(requestUrl);
          var queryString = getQueryString(requestUrl);

          var timestamp = new Date().toISOString().split('.')[0]+"Z";
          timestamp = timestamp.replace(/:/gi, "").replace(/-/gi, "").substring(2);

          var requestData = [timestamp, httpMethod, requestPath, queryString].join("");
          requestData = replaceVariables(requestData);
          var hash = CryptoJS.HmacSHA256(requestData, SECRET_KEY);
          var hmacDigest = CryptoJS.enc.Hex.stringify(hash);
          var authHeader = AUTH_TYPE + ", access-key=" + CLIENT_KEY + ', signed-date=' + timestamp + ', signature=' + hmacDigest;
          return authHeader;
}

function replaceVariables(templateString) {
          let tokens = _.uniq(templateString.match(/{{\w*}}/g))

    _.forEach(tokens, t => {
       let variable = t.replace(/[{}]/g, '')
       let value = environment[variable] || globals[variable]
       templateString = templateString.replace(new RegExp(t,'g'), value)
    });

    return templateString
}

pm.globals.set('signature', getAuthHeader(request['method'], request['url'], request['data']));

위 내용을 복사한 후 아래 이미지처럼 Pre-request script 탭 내에 붙여넣기 하시면 됩니다.

Copy the above and paste in the Pre-request script tab as in the image below.

4-5. Enter message body

When API request method is 'POST' or 'PUT', you sometimes have to write parameter in the message body. The parameter is called message body. Let's take a product registration API as an example. 

Select Body tab, 'raw' for message type and `JSON(aplication/json)`  for content type and write message body referring to API spec of developer portal. 

4-6. API Call

If you have entered all the URI, Method, Header, Parameter, Message  required for API call, click Send button to send API request. You can find how the response comes when the request succeeded and what the issue was in the request when failed. 

When you receive the response without any issue, response message is printed in the response window and HTTP200 response code is sent. 

 When there is an error, error message is sent with relevant error code. 

5. API call trouble shooting

What is important in the API service development is not to know how to use Postman but to understand API call response message.

5-1. Use of FAQ

 

Coupang developer portal provides the guide to understanding response message via FAQ.

You can find frequently asked questions using a search feature. Please search on FAQ before raising a question. 

5-2. Checking error code and message

• 4XX Error :
• 4 Most of  4XX errors are  API request type issues.  
• In this case, it is very likely that you can address the issue by entering correct info checking the error message.
• First, check if the data you used for calling matches with the API specification in the developers portal. If the issue persists, please raise a question with "call message" and "response message" attached. We will help to address the issue asap. 
• 5XX Error :
• Most of 5xx errors are the errors occur internally processing the API response. 
• To identify the cause precisely, please attach "call message" and "response message" when you raise an inquiry. We will help to address the issue asap. 

6. How to check POSTMAN call and response message

If you include both call message and response message referring to below when you raise an inquiry via Question, we can respond to your inquiry more quickly.

6-1. Provide call message

Click Code button at the right top of the window. 

You can copy the entire call message on the pop-up window to clip board. 

You can display call message in many formats but we recommend 'cURL' format.

6-2. Provide response message

Download the message in the json format using Download button. You can also paste it to the body using the copy button of clip board. Also please include http response code, too.