Context

Figure 2-2 API calling process (token authentication) for the O&M plane

• When a third-party system invokes northbound APIs of eSight, the request header must contain the authentication parameters of the eSight northbound user.
• You are advised to call the user authentication API to obtain the value of accessSession (the token value) of the eSight northbound user in token authentication mode.
• When northbound open APIs that transmit eSight resource information are called, accessSession is included in the Headers parameter of the request. The key is AccessSession, X-Auth-Token, X-Access-Token, or Openid. These four types of request headers have different names but the same functions. This section uses X-Auth-Token as an example.

Prerequisites

• When eSight interconnects with a third-party system through the API gateway, if certificate authentication is enabled on the third-party system, you need to configure the eSight northbound service certificate on the third-party system. For how to obtain the eSight northbound service certificate, see Obtaining and Configuring Certificates.
• By default, eSight does not verify the certificate of the third-party system. If the user has high security requirements, the user can manually enable the verification and import the certificate of the third-party system to eSight. For how to enable the verification and import the certificate of the third-party system to eSight, see Configuring Client Certificate Authentication for API Management (GUI Mode).

  To prevent security issues caused by private key leakage, periodically update the certificates to ensure system security. You need to update the certificate before it expires.

Procedure

1. Obtain the IP address and port number used by eSight to connect to external systems.

   A third-party system uses this IP address and port to call eSight open APIs. For details, see Obtaining and Configuring the IP Address and Port Number.

2. Create an eSight northbound user.

   When a third-party system calls an eSight open API, the token authentication information of the user must be included. For how to create a user, see Creating a User.

3. Log in to the backend node of the third-party system and run the cURL command to call the API in Authenticate a User to obtain the token information of the eSight northbound user.
   • For eSight V300R010 and earlier versions, call the API in Authenticate a User V2 (Compatible with V300R010 and Earlier Versions).
   • You can also use a tool, such as Postman or RESTClient, to call APIs. For details, see Using the API Tool to Call APIs.
   A cURL example is as follows:

   curl -k -s -L -i -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Accept-Language: en-US' -X PUT 'https://192.168.1.125:32102/rest/plat/smapp/v1/sessions' -d '{ "grantType":"password", "userName":"XXX", "value":"***"}'

   • 192.168.1.125:32102 indicates the IP address and port number used by eSight to connect to external systems. The value is obtained in 1.
   • PUT and /rest/plat/smapp/v1/sessions indicate the calling method of the API in Authenticate a User and the URI of the API.
   • grantType, userName, and value are mandatory parameters in the request body of the API in Authenticate a User. Set them to password and the eSight northbound user name and password created in 2 respectively.
   If the response status code is 200, the result is returned successfully. View the response result and record the value of accessSession, which is the token information of the eSight northbound user.

   {
     "accessSession": "x-yyyyyyy",
     "roaRand": "xxxxxxx",
     "expires": 1800,
     "additionalInfo": {
                         "expires":"2",
                         "passwdStatus":"expiring"
                        }
   }

4. Use a debugging tool or log in to the backend node of the third-party system and run the cURL command to call other open APIs to obtain eSight resource information. The request must include the token information of the eSight northbound user obtained in 3.
   For example, call the API in Querying Monitoring Resources to obtain the monitored object of the eSight performance monitoring service. A cURL example is as follows:

   curl -k -s -L -i -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Accept-Language: en-US' -X GET 'X-Auth-Token:x-yyyyyyy' 'https://192.168.1.125:32102/rest/openapi/dps-service/v1/resource?dn=7fd4486d-34b4-3cf9-aa6b-34ad20b7f5c6&objTypeKey=interface&indicatorKeys=ifXTrafficStat'

   • x-yyyyyyy indicates the token information of the eSight northbound user obtained in 3.
   • 192.168.1.125:32102 indicates the IP address and port number used by eSight to connect to external systems. The value is obtained in 1.
   • GET and rest/openapi/dps-service/v1/resource indicate the calling method of the API in Querying Monitoring Resources and the URL of the API.
   • dn, objTypeKey, and indicatorKeys are mandatory request parameters for calling the API in Querying Monitoring Resources. Set the parameters based on the API description.

   If the response status code is 200, the result is returned successfully. View the response result to obtain the queried monitored object.

   {
     "code": 0,
     "data": [{
       "objId": "281483566645259",
       "objName": "GigabitEthernet0/0/4"
     },{
       "objId": "281483566645296",
       "objName": "GigabitEthernet0/0/10"
     }],
     "description": "Successful."
   }

5. If a third-party system calls the subscription notification API (for details, see Message Notification Description) to subscribe to eSight notification messages, eSight northbound APIs report notification messages to the third-party system in Open ID authentication mode. You need to connect eSight with the RESTful server of the third-party system in advance. For details, see Preparation for Proactive RESTful Message Notification.
6. (Optional) When a third-party system calls eSight APIs, it may use the same IP address to frequently connect to eSight. By default, eSight does not limit the number of concurrent connections and connection frequency of the same IP address. To change the maximum number of concurrent connections and connection frequency, see Configuring the Limit of Concurrent Connections and Connection Frequency for One IP Address (GUI Mode).