Getting started

Step 1: Download and install Postman

Postman is a collaboration platform for API development. It covers the entire API lifecycle, including design, development, testing, and code generation.

Download and install Postman. For more information, see the official Postman documentation.

Step 2: Configure SSL

By default, Postman validates server-side Secure Sockets Layer (SSL) certificates. To ensure that API calls work correctly, you can choose one of the following methods to configure SSL:

• Disable SSL validation
  1. Open Postman.
  2. On the Postman homepage, click the icon in the upper-right corner and select Settings.
  3. In the SETTINGS dialog box, click the General tab, and then set SSL certificate verification to OFF.
• Configure a CA certificate

  Locate the OpenAPI server-side CA certificate in the /linkedge/gateway/build/bin/console/certs/ca.x509.pem directory on the machine that runs IoT Edge. Download the certificate to your computer. For more information about how to configure a CA certificate, see Step 1: Configure a certificate.

  1. Open Postman.
  2. On the Postman homepage, click the icon in the upper-right corner and select Settings.
  3. In the SETTINGS dialog box, click the Certificates tab, and then set CA Certificates to ON.
  4. Click Select File and upload the downloaded ca.x509.pem file to Postman.

Step 3: Test the API

You can use Postman to import API requests from cURL commands.

1. On the Postman homepage, click Import in the upper-left corner.
2. In the IMPORT dialog box, click the Raw Text tab and enter the cURL command for the CreateAuthCookie API.
   
3. Click Continue. On the Confirm your import page, Postman parses the cURL command and automatically populates the request fields. Click Import.
4. Click Send to send the request. A 201 Created status code is returned.
   The value of the Set-Cookie field in the response headers is the authentication cookie. Copy this value for later use.
5. After you obtain the authentication cookie, repeat Steps 1 to 4 to call other APIs.
   The following figure shows an example of calling the ListThings API. On the Postman homepage, click Import in the upper-left corner, enter the cURL command for the ListThings API request, and then click Continue > Import. Postman automatically populates the Cookie field in the ListThings request header with the value of the Set-Cookie field from the CreateAuthCookie API response. Then, click Send.

Step 4: Generate code

Postman can automatically generate call code.

1. In the tab for the successful API call, click Code on the right.
2. Select a language to generate the corresponding call code.
   

   The following examples show Postman-generated code for calling the ListThings API:

   • Node.js

     var https = require('https');
     
     var options = {
       'method': 'GET',
       'hostname': '127.0.0.1',
       'port': 9999,
       'path': '/2020-04-30/things',
       'headers': {
         'Cookie': 'token=2c2cbbc36af52216a6dd0bdba38f575e2b94b029d1bf45bb7a377f**********'
       },
     };
     
     var req = https.request(options, function (res) {
       var chunks = [];
       res.on("data", function (chunk) {
         chunks.push(chunk);
       });
       res.on("end", function (chunk) {
         var body = Buffer.concat(chunks);
         console.log(body.toString());
       });
       res.on("error", function (error) {
         console.error(error);
       });
     });
     req.end();

   • Python

     import requests
     
     url = "https://127.0.0.1:9999/2020-04-30/things"
     payload = {}
     headers = {
       'Cookie': 'token=2c2cbbc36af52216a6dd0bdba38f575e2b94b029d1bf45bb7a377f**********'
     }
     response = requests.request("GET", url, headers=headers, data = payload)
     print(response.text.encode('utf8'))

   • Java

     OkHttpClient client = new OkHttpClient().newBuilder()
       .build();
     Request request = new Request.Builder()
       .url("https://127.0.0.1:9999/2020-04-30/things")
       .method("GET", null)
       .addHeader("Cookie", "token=2c2cbbc36af52216a6dd0bdba38f575e2b94b029d1bf45bb7a377f**********")
       .build();
     Response response = client.newCall(request).execute();